asche

package module
v0.0.0-...-d4b318b Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 12, 2019 License: MIT Imports: 10 Imported by: 19

README

Asche

...because when you throw a gopher into volcano you get a pile of ash.

Asche is a high-level framework created to simplify development of Vulkan API applications using Go programming language. It manages Vulkan platform state and initialization, also provides an interface the app must conform in order to tell about desired platform requirements.

Currently it's used in VulkanCube demo app, please reference to it as an official Asche reference for now.

You should start by implementing this platform-describing interface:

type Application interface {
    VulkanInit(ctx Context) error
    VulkanAPIVersion() vk.Version
    VulkanAppVersion() vk.Version
    VulkanAppName() string
    VulkanMode() VulkanMode
    VulkanSurface(instance vk.Instance) vk.Surface
    VulkanInstanceExtensions() []string
    VulkanDeviceExtensions() []string
    VulkanDebug() bool

    // DECORATORS:
    // ApplicationSwapchainDimensions
    // ApplicationVulkanLayers
    // ApplicationContextPrepare
    // ApplicationContextCleanup
    // ApplicationContextInvalidate
}

Usually the cross-platform code may inherit (by embedding) the default app as.BaseVulkanApp, and later you wrap your cross-platform code into platform-specific (as shown in Android and Desktop demos of cube) overriding method implementations for that interface. VulkanInit() may stay here from default app, as it doesn't do anything other than storing context state. ApplicationContextPrepare() can be overriden in cross-platform code as it must implement the application-specific logic. And finally the platform code overrides VulkanSurface() as it should acquire a valid vk.Instance using platform-specific vk.CreateWindowSurface.

Decorators are considered to be optional methods that will be checked in runtime, with no default implementation, must be provided when needed by the app logic.

After platform intialization using as.NewPlatform, the application has access to this Vulkan Platform Interface:

type Platform interface {
    // MemoryProperties gets the current Vulkan physical device memory properties.
    MemoryProperties() vk.PhysicalDeviceMemoryProperties
    // PhysicalDeviceProperies gets the current Vulkan physical device properties.
    PhysicalDeviceProperies() vk.PhysicalDeviceProperties
    // GraphicsQueueFamilyIndex gets the current Vulkan graphics queue family index.
    GraphicsQueueFamilyIndex() uint32
    // PresentQueueFamilyIndex gets the current Vulkan present queue family index.
    PresentQueueFamilyIndex() uint32
    // HasSeparatePresentQueue is true when PresentQueueFamilyIndex differs from GraphicsQueueFamilyIndex.
    HasSeparatePresentQueue() bool
    // GraphicsQueue gets the current Vulkan graphics queue.
    GraphicsQueue() vk.Queue
    // PresentQueue gets the current Vulkan present queue.
    PresentQueue() vk.Queue
    // Instance gets the current Vulkan instance.
    Instance() vk.Instance
    // Device gets the current Vulkan device.
    Device() vk.Device
    // PhysicalDevice gets the current Vulkan physical device.
    PhysicalDevice() vk.PhysicalDevice
    // Surface gets the current Vulkan surface.
    Surface() vk.Surface
    // Destroy is the destructor for the Platform instance.
    Destroy()
}

And of course the Vulkan Context that can should be used in the app's logic and rendering loop:

type Context interface {
    // SetOnPrepare sets callback that will be invoked to initialize and prepare application's vulkan state
    // upon context prepare step. onCreate could create textures and pipelines,
    // descriptor layouts and render passes.
    SetOnPrepare(onPrepare func() error)
    // SetOnCleanup sets callback that will be invoked to cleanup application's vulkan state
    // upon context prepare step. onCreate could destroy textures and pipelines,
    // descriptor layouts and render passes.
    SetOnCleanup(onCleanup func() error)
    // SetOnInvalidate sets callback that will be invoked when context has been invalidated,
    // the application must update its state and prepare the corresponding swapchain image to be presented.
    // onInvalidate could compute new vertex and color data in swapchain image resource buffers.
    SetOnInvalidate(onInvalidate func(imageIdx int) error)
    // Device gets the Vulkan device assigned to the context.
    Device() vk.Device
    // Platform gets the current platform.
    Platform() Platform
    // CommandBuffer gets a command buffer currently active.
    CommandBuffer() vk.CommandBuffer
    // SwapchainDimensions gets the current swapchain dimensions, including pixel format.
    SwapchainDimensions() *SwapchainDimensions
    // SwapchainImageResources exposes the swapchain initialized image resources.
    SwapchainImageResources() []*SwapchainImageResources
    // AcquireNextImage
    AcquireNextImage() (imageIndex int, outdated bool, err error)
    // PresentImage
    PresentImage(imageIdx int) (outdated bool, err error)
}

Both Vulkan Platform Interface and Vulkan Context terms are made up just for clarity, please note that Vulkan API has a little to none amount of abstraction, so Asche provides this state management tools to free the developer from extra burden. However, it's too easy to create leaky abstractions for Vulkan API, so Asche tries to be as minimal and pragmatic as possible.

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	DefaultVulkanAppVersion = vk.MakeVersion(1, 0, 0)
	DefaultVulkanAPIVersion = vk.MakeVersion(1, 0, 0)
	DefaultVulkanMode       = VulkanCompute | VulkanGraphics | VulkanPresent
)

Functions

func DeviceExtensions 

func DeviceExtensions(gpu vk.PhysicalDevice) (names []string, err error)

DeviceExtensions gets a list of instance extensions available on the provided physical device.

func FindRequiredMemoryType 

func FindRequiredMemoryType(props vk.PhysicalDeviceMemoryProperties,
	deviceRequirements, hostRequirements vk.MemoryPropertyFlagBits) (uint32, bool)

func FindRequiredMemoryTypeFallback 

func FindRequiredMemoryTypeFallback(props vk.PhysicalDeviceMemoryProperties,
	deviceRequirements, hostRequirements vk.MemoryPropertyFlagBits) (uint32, bool)

func InstanceExtensions 

func InstanceExtensions() (names []string, err error)

InstanceExtensions gets a list of instance extensions available on the platform.

func LoadShaderModule 

func LoadShaderModule(device vk.Device, data []byte) (vk.ShaderModule, error)

func NewError 

func NewError(ret vk.Result) error

func ValidationLayers 

func ValidationLayers() (names []string, err error)

ValidationLayers gets a list of validation layers available on the platform.

func VulkanProjectionMat 

func VulkanProjectionMat(m *lin.Mat4x4, proj *lin.Mat4x4)

VulkanProjectionMat converts an OpenGL style projection matrix to Vulkan style projection matrix. Vulkan has a topLeft clipSpace with [0, 1] depth range instead of [-1, 1].

linmath outputs projection matrices in GL style clipSpace, perform a simple fixup step to change the projection to Vulkan style.

Types

type Application 

type Application interface {
	VulkanInit(ctx Context) error
	VulkanAPIVersion() vk.Version
	VulkanAppVersion() vk.Version
	VulkanAppName() string
	VulkanMode() VulkanMode
	VulkanSurface(instance vk.Instance) vk.Surface
	VulkanInstanceExtensions() []string
	VulkanDeviceExtensions() []string
	VulkanDebug() bool
}

type ApplicationContextCleanup 

type ApplicationContextCleanup interface {
	VulkanContextCleanup() error
}

type ApplicationContextInvalidate 

type ApplicationContextInvalidate interface {
	VulkanContextInvalidate(imageIdx int) error
}

type ApplicationContextPrepare 

type ApplicationContextPrepare interface {
	VulkanContextPrepare() error
}

type ApplicationSwapchainDimensions 

type ApplicationSwapchainDimensions interface {
	VulkanSwapchainDimensions() *SwapchainDimensions
}

type ApplicationVulkanLayers 

type ApplicationVulkanLayers interface {
	VulkanLayers() []string
}

type BaseVulkanApp 

type BaseVulkanApp struct {
	// contains filtered or unexported fields
}

func (*BaseVulkanApp) Context 

func (app *BaseVulkanApp) Context() Context

func (*BaseVulkanApp) VulkanAPIVersion 

func (app *BaseVulkanApp) VulkanAPIVersion() vk.Version

func (*BaseVulkanApp) VulkanAppName 

func (app *BaseVulkanApp) VulkanAppName() string

func (*BaseVulkanApp) VulkanAppVersion 

func (app *BaseVulkanApp) VulkanAppVersion() vk.Version

func (*BaseVulkanApp) VulkanDebug 

func (app *BaseVulkanApp) VulkanDebug() bool

func (*BaseVulkanApp) VulkanDeviceExtensions 

func (app *BaseVulkanApp) VulkanDeviceExtensions() []string

func (*BaseVulkanApp) VulkanInit 

func (app *BaseVulkanApp) VulkanInit(ctx Context) error

func (*BaseVulkanApp) VulkanInstanceExtensions 

func (app *BaseVulkanApp) VulkanInstanceExtensions() []string

func (*BaseVulkanApp) VulkanMode 

func (app *BaseVulkanApp) VulkanMode() VulkanMode

func (*BaseVulkanApp) VulkanSurface 

func (app *BaseVulkanApp) VulkanSurface(instance vk.Instance) vk.Surface

type Buffer 

type Buffer struct {

	// Buffer is the buffer object.
	Buffer vk.Buffer
	// Memory is the device memory backing buffer object.
	Memory vk.DeviceMemory
	// contains filtered or unexported fields
}

func CreateBuffer 

func CreateBuffer(device vk.Device, memProps vk.PhysicalDeviceMemoryProperties,
	data []byte, usage vk.BufferUsageFlagBits) *Buffer

func (*Buffer) Destroy 

func (b *Buffer) Destroy()

type Context 

type Context interface {
	// SetOnPrepare sets callback that will be invoked to initialize and prepare application's vulkan state
	// upon context prepare step. onCreate could create textures and pipelines,
	// descriptor layouts and render passes.
	SetOnPrepare(onPrepare func() error)
	// SetOnCleanup sets callback that will be invoked to cleanup application's vulkan state
	// upon context prepare step. onCreate could destroy textures and pipelines,
	// descriptor layouts and render passes.
	SetOnCleanup(onCleanup func() error)
	// SetOnInvalidate sets callback that will be invoked when context has been invalidated,
	// the application must update its state and prepare the corresponding swapchain image to be presented.
	// onInvalidate could compute new vertex and color data in swapchain image resource buffers.
	SetOnInvalidate(onInvalidate func(imageIdx int) error)
	// Device gets the Vulkan device assigned to the context.
	Device() vk.Device
	// Platform gets the current platform.
	Platform() Platform
	// CommandBuffer gets a command buffer currently active.
	CommandBuffer() vk.CommandBuffer
	// SwapchainDimensions gets the current swapchain dimensions, including pixel format.
	SwapchainDimensions() *SwapchainDimensions
	// SwapchainImageResources exposes the swapchain initialized image resources.
	SwapchainImageResources() []*SwapchainImageResources
	// AcquireNextImage
	AcquireNextImage() (imageIndex int, outdated bool, err error)
	// PresentImage
	PresentImage(imageIdx int) (outdated bool, err error)
}

type Platform 

type Platform interface {
	// MemoryProperties gets the current Vulkan physical device memory properties.
	MemoryProperties() vk.PhysicalDeviceMemoryProperties
	// PhysicalDeviceProperies gets the current Vulkan physical device properties.
	PhysicalDeviceProperies() vk.PhysicalDeviceProperties
	// GraphicsQueueFamilyIndex gets the current Vulkan graphics queue family index.
	GraphicsQueueFamilyIndex() uint32
	// PresentQueueFamilyIndex gets the current Vulkan present queue family index.
	PresentQueueFamilyIndex() uint32
	// HasSeparatePresentQueue is true when PresentQueueFamilyIndex differs from GraphicsQueueFamilyIndex.
	HasSeparatePresentQueue() bool
	// GraphicsQueue gets the current Vulkan graphics queue.
	GraphicsQueue() vk.Queue
	// PresentQueue gets the current Vulkan present queue.
	PresentQueue() vk.Queue
	// Instance gets the current Vulkan instance.
	Instance() vk.Instance
	// Device gets the current Vulkan device.
	Device() vk.Device
	// PhysicalDevice gets the current Vulkan physical device.
	PhysicalDevice() vk.PhysicalDevice
	// Surface gets the current Vulkan surface.
	Surface() vk.Surface
	// Destroy is the destructor for the Platform instance.
	Destroy()
}

func NewPlatform 

func NewPlatform(app Application) (pFace Platform, err error)

type StackFrame 

type StackFrame struct {
	File           string
	LineNumber     int
	Name           string
	Package        string
	ProgramCounter uintptr
}

A StackFrame contains all necessary information about to generate a line in a callstack.

func (*StackFrame) Func 

func (frame *StackFrame) Func() *runtime.Func

Func returns the function that this stackframe corresponds to

func (*StackFrame) SourceLine 

func (frame *StackFrame) SourceLine() (string, error)

SourceLine gets the line of code (from File and Line) of the original source if possible

func (*StackFrame) String 

func (frame *StackFrame) String() string

String returns the stackframe formatted in the same way as go does in runtime/debug.Stack()

type SwapchainDimensions 

type SwapchainDimensions struct {
	// Width of the swapchain.
	Width uint32
	// Height of the swapchain.
	Height uint32
	// Format is the pixel format of the swapchain.
	Format vk.Format
}

SwapchainDimensions describes the size and format of the swapchain.

type SwapchainImageResources 

type SwapchainImageResources struct {
	// contains filtered or unexported fields
}

func (*SwapchainImageResources) CommandBuffer 

func (s *SwapchainImageResources) CommandBuffer() vk.CommandBuffer

func (*SwapchainImageResources) DescriptorSet 

func (s *SwapchainImageResources) DescriptorSet() vk.DescriptorSet

func (*SwapchainImageResources) Destroy 

func (s *SwapchainImageResources) Destroy(dev vk.Device, cmdPool ...vk.CommandPool)

func (*SwapchainImageResources) Framebuffer 

func (s *SwapchainImageResources) Framebuffer() vk.Framebuffer

func (*SwapchainImageResources) Image 

func (s *SwapchainImageResources) Image() vk.Image

func (*SwapchainImageResources) SetDescriptorSet 

func (s *SwapchainImageResources) SetDescriptorSet(set vk.DescriptorSet)

func (*SwapchainImageResources) SetFramebuffer 

func (s *SwapchainImageResources) SetFramebuffer(fb vk.Framebuffer)

func (*SwapchainImageResources) SetImageOwnership 

func (s *SwapchainImageResources) SetImageOwnership(graphicsQueueFamilyIndex, presentQueueFamilyIndex uint32)

func (*SwapchainImageResources) SetUniformBuffer 

func (s *SwapchainImageResources) SetUniformBuffer(buffer vk.Buffer, mem vk.DeviceMemory)

func (*SwapchainImageResources) UniformBuffer 

func (s *SwapchainImageResources) UniformBuffer() vk.Buffer

func (*SwapchainImageResources) UniformMemory 

func (s *SwapchainImageResources) UniformMemory() vk.DeviceMemory

func (*SwapchainImageResources) View 

func (s *SwapchainImageResources) View() vk.ImageView

type VulkanMode 

type VulkanMode uint32
const (
	VulkanNone VulkanMode = (1 << iota) >> 1
	VulkanCompute
	VulkanGraphics
	VulkanPresent
)

func (VulkanMode) Has 

func (v VulkanMode) Has(mode VulkanMode) bool

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.