20.5. Boost — selection, builders, block brackets, conveniences

The hand-written ergonomic core: device/queue selection helpers, combined builders that fold several Vulkan objects into one owner (build_offscreen_target, create_host_buffer), block brackets (run_cmd_sync, record_render_pass, map_memory_to_array) that pair a begin/end or map/unmap around a block, and small conveniences (full_area, clear_color). This is the layer the examples are written against.

20.5.1. Constants

PIPELINE_STAGE_2_NONE = reinterpret<bitfield64:uint64<top_of_pipe;draw_indirect;vertex_input;vertex_shader;tessellation_control_shader;tessellation_evaluation_shader;geometry_shader;fragment_shader;early_fragment_tests;late_fragment_tests;color_attachment_output;compute_shader;all_transfer;bottom_of_pipe;host;all_graphics;all_commands;command_preprocess_ext;conditional_rendering_ext;task_shader_ext;mesh_shader_ext;ray_tracing_shader_khr;fragment_shading_rate_attachment_khr;fragment_density_process_ext;transform_feedback_ext;acceleration_structure_build_khr;video_decode_khr;video_encode_khr;acceleration_structure_copy_khr;optical_flow_nv;micromap_build_ext;_b31;copy;resolve;blit;clear;index_input;vertex_attribute_input;pre_rasterization_shaders;subpass_shader_huawei;invocation_mask_huawei;cluster_culling_shader_huawei;data_graph_arm;_b43;convert_cooperative_vector_matrix_nv;memory_decompression_ext;copy_indirect_khr> aka VkPipelineStageFlags2> bitfield64(0x0 )

PIPELINE_STAGE_2_NONE:bitfield64:uint64<top_of_pipe;draw_indirect;vertex_input;vertex_shader;tessellation_control_shader;tessellation_evaluation_shader;geometry_shader;fragment_shader;early_fragment_tests;late_fragment_tests;color_attachment_output;compute_shader;all_transfer;bottom_of_pipe;host;all_graphics;all_commands;command_preprocess_ext;conditional_rendering_ext;task_shader_ext;mesh_shader_ext;ray_tracing_shader_khr;fragment_shading_rate_attachment_khr;fragment_density_process_ext;transform_feedback_ext;acceleration_structure_build_khr;video_decode_khr;video_encode_khr;acceleration_structure_copy_khr;optical_flow_nv;micromap_build_ext;_b31;copy;resolve;blit;clear;index_input;vertex_attribute_input;pre_rasterization_shaders;subpass_shader_huawei;invocation_mask_huawei;cluster_culling_shader_huawei;data_graph_arm;_b43;convert_cooperative_vector_matrix_nv;memory_decompression_ext;copy_indirect_khr> const

ACCESS_2_NONE = reinterpret<bitfield64:uint64<indirect_command_read;index_read;vertex_attribute_read;uniform_read;input_attachment_read;shader_read;shader_write;color_attachment_read;color_attachment_write;depth_stencil_attachment_read;depth_stencil_attachment_write;transfer_read;transfer_write;host_read;host_write;memory_read;memory_write;command_preprocess_read_ext;command_preprocess_write_ext;color_attachment_read_noncoherent_ext;conditional_rendering_read_ext;acceleration_structure_read_khr;acceleration_structure_write_khr;fragment_shading_rate_attachment_read_khr;fragment_density_map_read_ext;transform_feedback_write_ext;transform_feedback_counter_read_ext;transform_feedback_counter_write_ext;_b28;_b29;_b30;_b31;shader_sampled_read;shader_storage_read;shader_storage_write;video_decode_read_khr;video_decode_write_khr;video_encode_read_khr;video_encode_write_khr;invocation_mask_read_huawei;shader_binding_table_read_khr;descriptor_buffer_read_ext;optical_flow_read_nv;optical_flow_write_nv;micromap_read_ext;micromap_write_ext;_b46;data_graph_read_arm;data_graph_write_arm;_b49;_b50;shader_tile_attachment_read_qcom;shader_tile_attachment_write_qcom;_b53;_b54;memory_decompression_read_ext;memory_decompression_write_ext;sampler_heap_read_ext;resource_heap_read_ext> aka VkAccessFlags2> bitfield64(0x0 )

ACCESS_2_NONE:bitfield64:uint64<indirect_command_read;index_read;vertex_attribute_read;uniform_read;input_attachment_read;shader_read;shader_write;color_attachment_read;color_attachment_write;depth_stencil_attachment_read;depth_stencil_attachment_write;transfer_read;transfer_write;host_read;host_write;memory_read;memory_write;command_preprocess_read_ext;command_preprocess_write_ext;color_attachment_read_noncoherent_ext;conditional_rendering_read_ext;acceleration_structure_read_khr;acceleration_structure_write_khr;fragment_shading_rate_attachment_read_khr;fragment_density_map_read_ext;transform_feedback_write_ext;transform_feedback_counter_read_ext;transform_feedback_counter_write_ext;_b28;_b29;_b30;_b31;shader_sampled_read;shader_storage_read;shader_storage_write;video_decode_read_khr;video_decode_write_khr;video_encode_read_khr;video_encode_write_khr;invocation_mask_read_huawei;shader_binding_table_read_khr;descriptor_buffer_read_ext;optical_flow_read_nv;optical_flow_write_nv;micromap_read_ext;micromap_write_ext;_b46;data_graph_read_arm;data_graph_write_arm;_b49;_b50;shader_tile_attachment_read_qcom;shader_tile_attachment_write_qcom;_b53;_b54;memory_decompression_read_ext;memory_decompression_write_ext;sampler_heap_read_ext;resource_heap_read_ext> const

20.5.2. Structures

RenderingFormats
Fields:

  • color : VkFormat - < the one color attachment; UNDEFINED for a depth-only pipeline

  • depth : VkFormat - < the depth attachment; UNDEFINED when the pipeline has none

  • info : VkPipelineRenderingCreateInfo - < the pNext struct attach_rendering_formats fills

SpecConstantValue

struct SpecConstantValue

OffscreenTarget

struct OffscreenTarget

OffscreenDepth

struct OffscreenDepth

HostBuffer

struct HostBuffer

AddressBuffer

struct AddressBuffer

ShaderBindingTable

struct ShaderBindingTable

AccelInstance

struct AccelInstance

AccelStructure

struct AccelStructure

20.5.3. Device selection

find_memory_type(phys: VkPhysicalDevice; type_bits: uint; want: VkMemoryPropertyFlags ): uint

def find_memory_type (phys: VkPhysicalDevice; type_bits: uint; want: VkMemoryPropertyFlags) : uint

Arguments:
select_graphics_queue_family(phys: VkPhysicalDevice ): uint

def select_graphics_queue_family (phys: VkPhysicalDevice) : uint

Arguments:
select_physical_device(instance: Instance ): VkPhysicalDevice

def select_physical_device (instance: Instance) : VkPhysicalDevice

Arguments:
try_find_memory_type(phys: VkPhysicalDevice; type_bits: uint; want: VkMemoryPropertyFlags ): int

def try_find_memory_type (phys: VkPhysicalDevice; type_bits: uint; want: VkMemoryPropertyFlags) : int

Arguments:

20.5.4. Instance & device

20.5.4.1. create_device

create_device(phys: VkPhysicalDevice; queue_families: array<uint>; extensions: array<string>; features2: VkPhysicalDeviceFeatures2 ): Device

def create_device (phys: VkPhysicalDevice; queue_families: array<uint>; extensions: array<string>; var features2: VkPhysicalDeviceFeatures2) : Device

Arguments:
create_device(phys: VkPhysicalDevice; queue_family: uint ): Device
create_device(phys: VkPhysicalDevice; queue_family: uint; extensions: array<string> ): Device
create_device(phys: VkPhysicalDevice; queue_family: uint; extensions: array<string>; features12: VkPhysicalDeviceVulkan12Features ): Device
create_device(phys: VkPhysicalDevice; queue_family: uint; extensions: array<string>; features13: VkPhysicalDeviceVulkan13Features ): Device
create_device(phys: VkPhysicalDevice; queue_family: uint; extensions: array<string>; features2: VkPhysicalDeviceFeatures2 ): Device
create_device(phys: VkPhysicalDevice; queue_family: uint; extensions: array<string>; features: VkPhysicalDeviceFeatures ): Device
create_device(phys: VkPhysicalDevice; queue_family: uint; extensions: array<string>; meshFeatures: VkPhysicalDeviceMeshShaderFeaturesEXT ): Device
create_device_descriptor_indexing(phys: VkPhysicalDevice; queue_family: uint ): Device

def create_device_descriptor_indexing (phys: VkPhysicalDevice; queue_family: uint) : Device

Arguments:
create_device_draw_parameters(phys: VkPhysicalDevice; queue_family: uint ): Device

def create_device_draw_parameters (phys: VkPhysicalDevice; queue_family: uint) : Device

Arguments:

20.5.4.2. create_device_shader_object

create_device_shader_object(phys: VkPhysicalDevice; queue_family: uint ): Device

def create_device_shader_object (phys: VkPhysicalDevice; queue_family: uint) : Device

Arguments:
create_device_shader_object(phys: VkPhysicalDevice; queue_family: uint; extensions: array<string> ): Device

20.5.4.3. create_device_vulkan14

create_device_vulkan14(phys: VkPhysicalDevice; queue_family: uint ): Device

def create_device_vulkan14 (phys: VkPhysicalDevice; queue_family: uint) : Device

Arguments:
create_device_vulkan14(phys: VkPhysicalDevice; queue_family: uint; extensions: array<string> ): Device

20.5.4.4. create_instance

create_instance(application_name: string = ""; api_version: uint = 0x0 ): Instance

def create_instance (application_name: string = “”; api_version: uint = 0x0) : Instance

Arguments:

  • application_name : string

  • api_version : uint

create_instance(application_name: string; api_version: uint; extensions: array<string> ): Instance
device_extension_available(phys: VkPhysicalDevice; name: string ): bool

def device_extension_available (phys: VkPhysicalDevice; name: string) : bool

Arguments:
dynamic_rendering_supported(phys: VkPhysicalDevice ): bool

True when the create_instance instance and phys are both 1.3 and the device reports dynamicRendering + synchronization2.

Arguments:
get_device_queue(device: Device; queue_family: uint; index: uint ): VkQueue

def get_device_queue (device: Device; queue_family: uint; index: uint) : VkQueue

Arguments:

  • device : Device

  • queue_family : uint

  • index : uint

instance_extension_available(name: string ): bool

def instance_extension_available (name: string) : bool

Arguments:

  • name : string

probe_device(application_name: string; api_version: uint; blk: block<(phys:VkPhysicalDevice):bool> ): bool

blk over the physical device of a throwaway api_version instance named application_name, for a test or tutorial that skips instead of panicking where a capability is missing: false with no loader or no device, else what blk answers. The instance is gone when this returns.

Arguments:

  • application_name : string

  • api_version : uint

  • blk : block<(phys: VkPhysicalDevice):bool>

shader_object_supported(phys: VkPhysicalDevice ): bool

True when phys advertises VK_EXT_shader_object, reports its shaderObject feature and dynamic_rendering_supported holds, since a shader-object draw records inside a dynamic rendering - what create_device_shader_object enables.

Arguments:
vulkan14_supported(phys: VkPhysicalDevice ): bool

True when the create_instance instance and phys are both 1.4 and the device reports pushDescriptor, hostImageCopy and dynamicRenderingLocalRead - what create_device_vulkan14 enables.

Arguments:

20.5.5. Host image copy

host_copy_layout(phys: VkPhysicalDevice; wanted: VkImageLayout ): VkImageLayout

The layout a host image copy into a phys image can land in: wanted when the device lists it among its copy destinations (VkPhysicalDeviceHostImageCopyProperties), else GENERAL, which every device lists. Panics unless vulkan14_supported(phys).

Arguments:
upload_image_from_host(device: Device; image: Image; pixels: array<uint8>; width: int; height: int; layout: VkImageLayout; texel_bytes: int = 4 )

Fills mip 0, layer 0 of image (usage host_transfer, idle on the device) from tightly packed pixels of width x height x texel_bytes, with no staging buffer and no command buffer: a host-side transition into layout (from host_copy_layout) then one vkCopyMemoryToImage. Panics unless the latest create_device* call was create_device_vulkan14.

Arguments:

20.5.6. Shader objects

cmd_bind_graphics_shaders(cmd: CommandBuffer; vert: ShaderEXT; frag: ShaderEXT )

Binds vert and frag as the vertex and fragment shader objects with the tessellation and geometry slots emptied, on a device from create_device_shader_object (one with task or mesh shaders on must empty those slots too); the fixed-function state comes from cmd_set_shader_object_baseline.

Arguments:
cmd_set_shader_object_baseline(cmd: CommandBuffer; width: int; height: int; color_attachments: uint )

The dynamic state a draw with bound shader objects needs on a device from create_device_shader_object, in the shape a pipeline fixes: a full-extent viewport and scissor, filled triangles, one sample, no culling, CCW front faces, depth and stencil tests off, no vertex input, color_attachments opaque writes.

Arguments:

  • cmd : CommandBuffer

  • width : int

  • height : int

  • color_attachments : uint

spirv_bytes(words: array<uint> ): array<uint8>

A SPIR-V word blob as the byte array ShaderCreateInfoEXT.pCode takes.

Arguments:

  • words : array<uint>

20.5.7. Shaders & pipelines

20.5.7.1. create_compute_pipeline

create_compute_pipeline(device: Device; layout: PipelineLayout; shader: ShaderModule; entry: string = "main" ): Pipeline

def create_compute_pipeline (device: Device; layout: PipelineLayout; shader: ShaderModule; entry: string = “main”) : Pipeline

Arguments:
create_compute_pipeline(device: Device; layout: PipelineLayout; shader: ShaderModule; spec: array<SpecConstantValue>; entry: string = "main" ): Pipeline
create_compute_pipeline_full_subgroups(device: Device; layout: PipelineLayout; shader: ShaderModule; entry: string = "main" ): Pipeline

def create_compute_pipeline_full_subgroups (device: Device; layout: PipelineLayout; shader: ShaderModule; entry: string = “main”) : Pipeline

Arguments:
create_graphics_pipeline_dyn(device: Device; color_format: VkFormat; depth_format: VkFormat; samples: VkSampleCountFlags; layout: PipelineLayout; vert: ShaderModule; frag: ShaderModule; width: int; height: int; vertex_bindings: array<VkVertexInputBindingDescription>; vertex_attributes: array<VkVertexInputAttributeDescription>; depth_test_enable: bool = true; depth_write_enable: bool = true; depth_compare_op: VkCompareOp = vulkan::VkCompareOp.LESS_OR_EQUAL; dynamic_viewport: bool = false ): Pipeline

The format overload of create_graphics_pipeline_v3d with a sample count: samples sets the rasterization samples, color_format and depth_format ride in a VkPipelineRenderingCreateInfo. Tutorial 09 drives it at 4x.

Arguments:

20.5.7.2. create_graphics_pipeline_simple

create_graphics_pipeline_simple(device: Device; color_format: VkFormat; layout: PipelineLayout; vert: ShaderModule; frag: ShaderModule; width: int; height: int; dynamic_viewport: bool = false ): Pipeline

Dynamic-rendering twin of create_graphics_pipeline_simple: the pipeline carries color_format in a VkPipelineRenderingCreateInfo instead of a render pass, so it draws inside record_rendering on any view of that format - an offscreen target or a swapchain image - with no depth attachment.

Arguments:
create_graphics_pipeline_simple(device: Device; render_pass: RenderPass; layout: PipelineLayout; vert: ShaderModule; frag: ShaderModule; width: int; height: int; dynamic_viewport: bool = false ): Pipeline

20.5.7.3. create_graphics_pipeline_v3d

create_graphics_pipeline_v3d(device: Device; color_format: VkFormat; depth_format: VkFormat; layout: PipelineLayout; vert: ShaderModule; frag: ShaderModule; width: int; height: int; vertex_bindings: array<VkVertexInputBindingDescription>; vertex_attributes: array<VkVertexInputAttributeDescription>; depth_test_enable: bool = true; depth_write_enable: bool = true; depth_compare_op: VkCompareOp = vulkan::VkCompareOp.LESS_OR_EQUAL; dynamic_viewport: bool = false ): Pipeline

Dynamic-rendering twin of create_graphics_pipeline_v3d: color_format and depth_format ride in a VkPipelineRenderingCreateInfo instead of a render pass - create_graphics_pipeline_dyn with one sample per pixel. A depth format of UNDEFINED leaves depth testing off.

Arguments:
create_graphics_pipeline_v3d(device: Device; render_pass: RenderPass; layout: PipelineLayout; vert: ShaderModule; frag: ShaderModule; width: int; height: int; vertex_bindings: array<VkVertexInputBindingDescription>; vertex_attributes: array<VkVertexInputAttributeDescription>; depth_test_enable: bool = true; depth_write_enable: bool = true; depth_compare_op: VkCompareOp = vulkan::VkCompareOp.LESS_OR_EQUAL; dynamic_viewport: bool = false ): Pipeline
create_pipeline_layout(device: Device ): PipelineLayout

def create_pipeline_layout (device: Device) : PipelineLayout

Arguments:

20.5.7.4. create_shader_module

create_shader_module(device: Device; code: array<uint8> ): ShaderModule

def create_shader_module (device: Device; var code: array<uint8>) : ShaderModule

Arguments:

  • device : Device

  • code : array<uint8>

create_shader_module(device: Device; code: array<uint> ): ShaderModule

20.5.8. Dynamic rendering

attach_rendering_formats(gp: VkGraphicsPipelineCreateInfo; fmts: RenderingFormats )

Chains fmts.info, filled from fmts, at the head of gp.pNext - what the chain held before follows it. A pipeline built this way draws inside record_rendering on any view of these formats; fmts must outlive the pipeline creation.

Arguments:

20.5.8.1. record_rendering

record_rendering(cmd: CommandBuffer; area: VkRect2D; layer_count: uint; color_attachments: array<RenderingAttachmentInfo>; blk: block<():void> )

def record_rendering (cmd: CommandBuffer; area: VkRect2D; layer_count: uint; var color_attachments: array<RenderingAttachmentInfo>; blk: block<():void>)

Arguments:
record_rendering(cmd: CommandBuffer; area: VkRect2D; layer_count: uint; color_attachments: array<RenderingAttachmentInfo>; depth_attachment: RenderingAttachmentInfo; blk: block<():void> )
record_rendering(cmd: CommandBuffer; color_view: ImageView; area: VkRect2D; clear: VkClearValue; load_op: VkAttachmentLoadOp = vulkan::VkAttachmentLoadOp.CLEAR; blk: block<():void> )
record_rendering(cmd: CommandBuffer; color_view: ImageView; depth_view: ImageView; area: VkRect2D; clears: array<VkClearValue>; blk: block<():void> )
record_rendering_depth_only(cmd: CommandBuffer; depth_view: ImageView; area: VkRect2D; clear: VkClearValue; blk: block<():void> )

The dynamic-rendering twin of a create_render_pass_depth_only pass: no color attachment, the depth view cleared to clear and STORED, for a shadow map or a depth pre-pass that a later pass reads.

Arguments:
render_offscreen_rgba8(device: Device; phys: VkPhysicalDevice; queue: VkQueue; pool: CommandPool; target: OffscreenTarget; width: int; height: int; clear: VkClearValue; blk: block<(cmd:CommandBuffer):void> ): array<uint8>

One synchronous frame on target (a build_offscreen_target of width x height, RGBA8): the image moves to COLOR_ATTACHMENT_OPTIMAL, blk records inside record_rendering cleared to clear, the image moves to TRANSFER_SRC_OPTIMAL and is copied out; returns the width * height * 4 bytes.

Arguments:
rendering_color_attachment(view: ImageView; clear: VkClearValue; load_op: VkAttachmentLoadOp = vulkan::VkAttachmentLoadOp.CLEAR; store_op: VkAttachmentStoreOp = vulkan::VkAttachmentStoreOp.STORE ): RenderingAttachmentInfo

A color attachment for record_rendering: view in COLOR_ATTACHMENT_OPTIMAL, load_op on entry (CLEAR takes clear), store_op on exit. The view’s image must already be in that layout - the caller’s transition_image2 puts it there.

Arguments:
rendering_depth_attachment(view: ImageView; clear: VkClearValue; store_op: VkAttachmentStoreOp = vulkan::VkAttachmentStoreOp.DONT_CARE ): RenderingAttachmentInfo

A depth attachment for record_rendering: view in DEPTH_ATTACHMENT_OPTIMAL, cleared to clear (clear_depth), store_op on exit - DONT_CARE when nothing reads the depth afterwards, STORE for a shadow map or a depth pre-pass.

Arguments:
rendering_formats(color_format: VkFormat; depth_format: VkFormat = vulkan::VkFormat.UNDEFINED ): RenderingFormats

The RenderingFormats of a pipeline drawing into color_format and depth_format views; UNDEFINED leaves that attachment out.

Arguments:
require_dynamic_rendering(what: string )

Panics, naming what, when the latest create_device* left dynamicRendering + synchronization2 off - the instance or device could not give them, or a features13 caller did not set them; the _2 entry points are null there, and a call into one would crash with no message.

Arguments:

  • what : string

set_pipeline_target(gp: VkGraphicsPipelineCreateInfo; render_pass: RenderPass; fmts: RenderingFormats )

Points a VkGraphicsPipelineCreateInfo at its target: render_pass when it holds a handle, else the dynamic-rendering fmts through attach_rendering_formats. The one place a pipeline builder that serves both frame loops decides between them.

Arguments:

20.5.9. Mesh shaders

create_device_mesh_shader(phys: VkPhysicalDevice; queue_family: uint ): Device

def create_device_mesh_shader (phys: VkPhysicalDevice; queue_family: uint) : Device

Arguments:

20.5.9.1. create_mesh_pipeline

create_mesh_pipeline(device: Device; color_format: VkFormat; depth_format: VkFormat; layout: PipelineLayout; task: ShaderModule; mesh: ShaderModule; frag: ShaderModule; width: int; height: int; dynamic_viewport: bool = false ): Pipeline

Dynamic-rendering twin of create_mesh_pipeline: color_format and depth_format ride in a VkPipelineRenderingCreateInfo instead of a render pass; depth test + write are on exactly when a depth format is given.

Arguments:
create_mesh_pipeline(device: Device; render_pass: RenderPass; layout: PipelineLayout; task: ShaderModule; mesh: ShaderModule; frag: ShaderModule; width: int; height: int; dynamic_viewport: bool = false; enable_depth: bool = false ): Pipeline
mesh_shader_supported(phys: VkPhysicalDevice ): bool

True when phys advertises VK_EXT_mesh_shader and reports meshShader + taskShader: a driver can list the extension yet report a bit as 0, and vkCreateDevice fails on it. Gate mesh setup with this.

Arguments:

20.5.10. Hardware ray tracing

build_blas(device: Device; phys: VkPhysicalDevice; pool: CommandPool; queue: VkQueue; vertices: array<float3>; indices: array<uint> ): AccelStructure

def build_blas (device: Device; phys: VkPhysicalDevice; pool: CommandPool; queue: VkQueue; var vertices: array<float3>; var indices: array<uint>) : AccelStructure

Arguments:
build_shader_binding_table(device: Device; phys: VkPhysicalDevice; pipeline: Pipeline; miss_count: uint; hit_count: uint ): ShaderBindingTable

def build_shader_binding_table (device: Device; phys: VkPhysicalDevice; pipeline: Pipeline; miss_count: uint; hit_count: uint) : ShaderBindingTable

Arguments:
build_tlas(device: Device; phys: VkPhysicalDevice; pool: CommandPool; queue: VkQueue; instances: array<AccelInstance> ): AccelStructure

def build_tlas (device: Device; phys: VkPhysicalDevice; pool: CommandPool; queue: VkQueue; var instances: array<AccelInstance>) : AccelStructure

Arguments:
cmd_trace_rays(cmd: CommandBuffer; sbt: ShaderBindingTable; width: uint; height: uint; depth: uint = 0x1 )

def cmd_trace_rays (cmd: CommandBuffer; sbt: ShaderBindingTable; width: uint; height: uint; depth: uint = 0x1)

Arguments:
create_address_buffer(device: Device; phys: VkPhysicalDevice; size: uint64; usage: VkBufferUsageFlags; host_visible: bool ): AddressBuffer

def create_address_buffer (device: Device; phys: VkPhysicalDevice; size: uint64; usage: VkBufferUsageFlags; host_visible: bool) : AddressBuffer

Arguments:

20.5.10.1. create_device_ray_tracing

create_device_ray_tracing(phys: VkPhysicalDevice; queue_family: uint ): Device

def create_device_ray_tracing (phys: VkPhysicalDevice; queue_family: uint) : Device

Arguments:
create_device_ray_tracing(phys: VkPhysicalDevice; queue_family: uint; extra_extensions: array<string> ): Device

20.5.10.2. create_ray_tracing_pipeline

create_ray_tracing_pipeline(device: Device; layout: PipelineLayout; raygen: ShaderModule; miss: ShaderModule; closest_hit: ShaderModule; max_recursion: uint = 0x1 ): Pipeline

def create_ray_tracing_pipeline (device: Device; layout: PipelineLayout; raygen: ShaderModule; miss: ShaderModule; closest_hit: ShaderModule; max_recursion: uint = 0x1) : Pipeline

Arguments:
create_ray_tracing_pipeline(device: Device; layout: PipelineLayout; raygen: ShaderModule; miss: array<ShaderModule>; closest_hit: ShaderModule; max_recursion: uint = 0x1 ): Pipeline
get_ray_tracing_properties(phys: VkPhysicalDevice ): VkPhysicalDeviceRayTracingPipelinePropertiesKHR

def get_ray_tracing_properties (phys: VkPhysicalDevice) : VkPhysicalDeviceRayTracingPipelinePropertiesKHR

Arguments:
get_ray_tracing_shader_group_handles(device: Device; pipeline: Pipeline; first_group: uint; group_count: uint; handle_size: uint ): array<uint8>

def get_ray_tracing_shader_group_handles (device: Device; pipeline: Pipeline; first_group: uint; group_count: uint; handle_size: uint) : array<uint8>

Arguments:

  • device : Device

  • pipeline : Pipeline

  • first_group : uint

  • group_count : uint

  • handle_size : uint

make_accel_instance(blas_address: uint64; custom_index: uint = 0x0; mask: uint = 0xff; sbt_record_offset: uint = 0x0; flags: uint = 0x0 ): AccelInstance

def make_accel_instance (blas_address: uint64; custom_index: uint = 0x0; mask: uint = 0xff; sbt_record_offset: uint = 0x0; flags: uint = 0x0) : AccelInstance

Arguments:

  • blas_address : uint64

  • custom_index : uint

  • mask : uint

  • sbt_record_offset : uint

  • flags : uint

rt_supported(phys: VkPhysicalDevice ): bool

def rt_supported (phys: VkPhysicalDevice) : bool

Arguments:
write_descriptor_acceleration_structure(device: Device; dset: DescriptorSet; binding: uint; tlas: AccelStructure )

def write_descriptor_acceleration_structure (device: Device; dset: DescriptorSet; binding: uint; tlas: AccelStructure)

Arguments:

20.5.11. Render passes

create_render_pass_color_depth(device: Device; color_format: VkFormat; depth_format: VkFormat; color_final_layout: VkImageLayout = vulkan::VkImageLayout.TRANSFER_SRC_OPTIMAL ): RenderPass

def create_render_pass_color_depth (device: Device; color_format: VkFormat; depth_format: VkFormat; color_final_layout: VkImageLayout = vulkan::VkImageLayout.TRANSFER_SRC_OPTIMAL) : RenderPass

Arguments:
create_render_pass_depth_only(device: Device; depth_format: VkFormat; final_layout: VkImageLayout = vulkan::VkImageLayout.DEPTH_STENCIL_READ_ONLY_OPTIMAL ): RenderPass

def create_render_pass_depth_only (device: Device; depth_format: VkFormat; final_layout: VkImageLayout = vulkan::VkImageLayout.DEPTH_STENCIL_READ_ONLY_OPTIMAL) : RenderPass

Arguments:
create_render_pass_single_color(device: Device; format: VkFormat; final_layout: VkImageLayout = vulkan::VkImageLayout.TRANSFER_SRC_OPTIMAL ): RenderPass

def create_render_pass_single_color (device: Device; format: VkFormat; final_layout: VkImageLayout = vulkan::VkImageLayout.TRANSFER_SRC_OPTIMAL) : RenderPass

Arguments:

20.5.12. Builders

build_image(device: Device; phys: VkPhysicalDevice; width: int; height: int; format: VkFormat; samples: VkSampleCountFlags; usage: VkImageUsageFlags ): OffscreenTarget

A device-local 2D image of format with exactly usage, its memory and a color view, owned together: what build_offscreen_target builds once it has added color_attachment, for an image that is not a render target - a texture filled by upload_image_from_host carries sampled + host_transfer.

Arguments:

20.5.12.1. build_offscreen_depth

build_offscreen_depth(device: Device; phys: VkPhysicalDevice; width: int; height: int; format: VkFormat = vulkan::VkFormat.D32_SFLOAT ): OffscreenDepth

def build_offscreen_depth (device: Device; phys: VkPhysicalDevice; width: int; height: int; format: VkFormat = vulkan::VkFormat.D32_SFLOAT) : OffscreenDepth

Arguments:
build_offscreen_depth(device: Device; phys: VkPhysicalDevice; width: int; height: int; format: VkFormat; extra_usage: VkImageUsageFlags ): OffscreenDepth
build_offscreen_depth(device: Device; phys: VkPhysicalDevice; width: int; height: int; format: VkFormat; extra_usage: VkImageUsageFlags; samples: VkSampleCountFlags ): OffscreenDepth

20.5.12.2. build_offscreen_target

build_offscreen_target(device: Device; phys: VkPhysicalDevice; width: int; height: int; format: VkFormat ): OffscreenTarget

def build_offscreen_target (device: Device; phys: VkPhysicalDevice; width: int; height: int; format: VkFormat) : OffscreenTarget

Arguments:
build_offscreen_target(device: Device; phys: VkPhysicalDevice; width: int; height: int; format: VkFormat; samples: VkSampleCountFlags; extra_usage: VkImageUsageFlags ): OffscreenTarget
compute_to_storage_image(words: array<uint>; w: int; h: int; srgb_encode: bool = false ): array<uint8>

def compute_to_storage_image (var words: array<uint>; w: int; h: int; srgb_encode: bool = false) : array<uint8>

Arguments:

  • words : array<uint>

  • w : int

  • h : int

  • srgb_encode : bool

20.5.12.3. create_host_buffer

create_host_buffer(device: Device; phys: VkPhysicalDevice; size: uint64 ): HostBuffer

def create_host_buffer (device: Device; phys: VkPhysicalDevice; size: uint64) : HostBuffer

Arguments:
create_host_buffer(device: Device; phys: VkPhysicalDevice; size: uint64; usage: VkBufferUsageFlags ): HostBuffer
create_host_buffer_from_bytes(device: Device; phys: VkPhysicalDevice; usage: VkBufferUsageFlags; data: array<auto(TT)> ): HostBuffer

def create_host_buffer_from_bytes (device: Device; phys: VkPhysicalDevice; usage: VkBufferUsageFlags; var data: array<auto(TT)>) : HostBuffer

Arguments:
create_sampler_shadow(device: Device; compare_op: VkCompareOp = vulkan::VkCompareOp.LESS ): Sampler

def create_sampler_shadow (device: Device; compare_op: VkCompareOp = vulkan::VkCompareOp.LESS) : Sampler

Arguments:

20.5.13. Memory & brackets

begin_one_time_commands(device: Device; pool: CommandPool ): VkCommandBuffer

One primary command buffer from pool, allocated and begun. The caller ends it, submits it and frees it back to pool - run_cmd_sync and the window layer’s submit_and_present pair do.

Arguments:
map_memory_to_array(device: Device; memory: DeviceMemory; size: uint64; blk: block<(data:array<uint8>):void> )

def map_memory_to_array (device: Device; memory: DeviceMemory; size: uint64; blk: block<(data:array<uint8>):void>)

Arguments:

  • device : Device

  • memory : DeviceMemory

  • size : uint64

  • blk : block<(data:array<uint8>):void>

read_memory(device: Device; memory: DeviceMemory; elem: type<auto(TT) const>; count: int ): array<TT>

def read_memory (device: Device; memory: DeviceMemory; elem: type<auto(TT) const>; count: int) : array<TT>

Arguments:

20.5.13.1. record_render_pass

record_render_pass(cmd: CommandBuffer; render_pass: RenderPass; framebuffer: Framebuffer; area: VkRect2D; clear: VkClearValue; blk: block<():void> )

def record_render_pass (cmd: CommandBuffer; render_pass: RenderPass; framebuffer: Framebuffer; area: VkRect2D; clear: VkClearValue; blk: block<():void>)

Arguments:
record_render_pass(cmd: CommandBuffer; render_pass: RenderPass; framebuffer: Framebuffer; area: VkRect2D; clears: array<VkClearValue>; blk: block<():void> )
run_cmd_sync(device: Device; pool: CommandPool; queue: VkQueue; blk: block<(cmd:CommandBuffer):void> )

def run_cmd_sync (device: Device; pool: CommandPool; queue: VkQueue; blk: block<(cmd:CommandBuffer):void>)

Arguments:

20.5.13.2. upload_bytes

upload_bytes(buf: AddressBuffer; device: Device; data: array<auto(TT)> ): auto

def upload_bytes (buf: AddressBuffer; device: Device; var data: array<auto(TT)>) : auto

Arguments:
upload_bytes(buf: HostBuffer; device: Device; data: array<auto(TT)> ): auto
with_mapped_memory(device: Device; memory: DeviceMemory; blk: block<(ptr:void?):void> )

def with_mapped_memory (device: Device; memory: DeviceMemory; blk: block<(ptr:void?):void>)

Arguments:
with_push_staging(size: uint; blk: block<(ptr:void?):void> )

def with_push_staging (size: uint; blk: block<(ptr:void?):void>)

Arguments:

  • size : uint

  • blk : block<(ptr:void?):void>

write_field(ptr: void?; offset: uint; value: auto(TT) ): auto

def write_field (ptr: void?; offset: uint; var value: auto(TT)) : auto

Arguments:

  • ptr : void?

  • offset : uint

  • value : auto(TT)

20.5.14. Command recording

blit_full_image(cmd: CommandBuffer; src: VkImage; src_layout: VkImageLayout; src_width: int; src_height: int; dst: VkImage; dst_layout: VkImageLayout; dst_width: int; dst_height: int; filter: VkFilter )

One vkCmdBlitImage of the whole of src (src_width x src_height, in src_layout) over the whole of dst (dst_width x dst_height, in dst_layout): color aspect, mip 0, one layer, scaled with filter when the extents differ.

Arguments:
cmd_bind_pipeline(cmd: CommandBuffer; pipeline: Pipeline; bind_point: VkPipelineBindPoint = vulkan::VkPipelineBindPoint.GRAPHICS )

def cmd_bind_pipeline (cmd: CommandBuffer; pipeline: Pipeline; bind_point: VkPipelineBindPoint = vulkan::VkPipelineBindPoint.GRAPHICS)

Arguments:
cmd_bind_vertex_buffer(cmd: CommandBuffer; binding: uint; buffer: Buffer; offset: uint64 = 0x0 )

def cmd_bind_vertex_buffer (cmd: CommandBuffer; binding: uint; buffer: Buffer; offset: uint64 = 0x0)

Arguments:
cmd_draw(cmd: CommandBuffer; vertex_count: uint; instance_count: uint = 0x1 )

def cmd_draw (cmd: CommandBuffer; vertex_count: uint; instance_count: uint = 0x1)

Arguments:
cmd_push_constants(cmd: CommandBuffer; layout: PipelineLayout; stages: VkShaderStageFlags; offset: uint; value: auto(TT) ): auto

def cmd_push_constants (cmd: CommandBuffer; layout: PipelineLayout; stages: VkShaderStageFlags; offset: uint; var value: auto(TT)) : auto

Arguments:
copy_image_to_buffer(cmd: CommandBuffer; image: Image; buffer: HostBuffer; width: int; height: int )

def copy_image_to_buffer (cmd: CommandBuffer; image: Image; buffer: HostBuffer; width: int; height: int)

Arguments:
transition_depth_image(cmd: CommandBuffer; image: Image; old_layout: VkImageLayout; new_layout: VkImageLayout; src_access: VkAccessFlags; dst_access: VkAccessFlags; src_stage: VkPipelineStageFlags; dst_stage: VkPipelineStageFlags )

def transition_depth_image (cmd: CommandBuffer; image: Image; old_layout: VkImageLayout; new_layout: VkImageLayout; src_access: VkAccessFlags; dst_access: VkAccessFlags; src_stage: VkPipelineStageFlags; dst_stage: VkPipelineStageFlags)

Arguments:
transition_depth_image2(cmd: CommandBuffer; image: Image; old_layout: VkImageLayout; new_layout: VkImageLayout; src_stage: VkPipelineStageFlags2; src_access: VkAccessFlags2; dst_stage: VkPipelineStageFlags2; dst_access: VkAccessFlags2 )

Depth-aspect transition_image_aspect2 - the synchronization2 transition_depth_image.

Arguments:
transition_image(cmd: CommandBuffer; image: Image; old_layout: VkImageLayout; new_layout: VkImageLayout; src_access: VkAccessFlags; dst_access: VkAccessFlags; src_stage: VkPipelineStageFlags; dst_stage: VkPipelineStageFlags )

def transition_image (cmd: CommandBuffer; image: Image; old_layout: VkImageLayout; new_layout: VkImageLayout; src_access: VkAccessFlags; dst_access: VkAccessFlags; src_stage: VkPipelineStageFlags; dst_stage: VkPipelineStageFlags)

Arguments:
transition_image2(cmd: CommandBuffer; image: Image; old_layout: VkImageLayout; new_layout: VkImageLayout; src_stage: VkPipelineStageFlags2; src_access: VkAccessFlags2; dst_stage: VkPipelineStageFlags2; dst_access: VkAccessFlags2 )

Color-aspect transition_image_aspect2 - the synchronization2 transition_image.

Arguments:
transition_image_aspect(cmd: CommandBuffer; image: Image; old_layout: VkImageLayout; new_layout: VkImageLayout; src_access: VkAccessFlags; dst_access: VkAccessFlags; src_stage: VkPipelineStageFlags; dst_stage: VkPipelineStageFlags; aspect: VkImageAspectFlags )

def transition_image_aspect (cmd: CommandBuffer; image: Image; old_layout: VkImageLayout; new_layout: VkImageLayout; src_access: VkAccessFlags; dst_access: VkAccessFlags; src_stage: VkPipelineStageFlags; dst_stage: VkPipelineStageFlags; aspect: VkImageAspectFlags)

Arguments:
transition_image_aspect2(cmd: CommandBuffer; image: Image; old_layout: VkImageLayout; new_layout: VkImageLayout; src_stage: VkPipelineStageFlags2; src_access: VkAccessFlags2; dst_stage: VkPipelineStageFlags2; dst_access: VkAccessFlags2; aspect: VkImageAspectFlags; level_count: uint = 0x1; layer_count: uint = 0x1 )

transition_image_aspect on synchronization2: the same layout move through cmd_pipeline_barrier2 with the 64-bit flags in barrier order (source stage and access, destination stage and access; PIPELINE_STAGE_2_NONE / ACCESS_2_NONE for an idle side), over level_count mips and layer_count layers.

Arguments:

20.5.15. Conveniences

clear_color(r: float; g: float; b: float; a: float ): VkClearValue

def clear_color (r: float; g: float; b: float; a: float) : VkClearValue

Arguments:

  • r : float

  • g : float

  • b : float

  • a : float

clear_depth(depth: float = 1f; stencil: uint = 0x0 ): VkClearValue

def clear_depth (depth: float = 1f; stencil: uint = 0x0) : VkClearValue

Arguments:

  • depth : float

  • stencil : uint

full_area(width: int; height: int ): VkRect2D

def full_area (width: int; height: int) : VkRect2D

Arguments:

  • width : int

  • height : int

20.5.16. Compute tier & device capabilities

compute_full_subgroups_supported(phys: VkPhysicalDevice ): bool

def compute_full_subgroups_supported (phys: VkPhysicalDevice) : bool

Arguments:
cooperative_matrix2_decode_vector_supported(phys: VkPhysicalDevice ): bool

def cooperative_matrix2_decode_vector_supported (phys: VkPhysicalDevice) : bool

Arguments:
cooperative_matrix2_fa_supported(phys: VkPhysicalDevice ): bool

def cooperative_matrix2_fa_supported (phys: VkPhysicalDevice) : bool

Arguments:
cooperative_matrix2_properties(phys: VkPhysicalDevice ): VkPhysicalDeviceCooperativeMatrix2PropertiesNV

def cooperative_matrix2_properties (phys: VkPhysicalDevice) : VkPhysicalDeviceCooperativeMatrix2PropertiesNV

Arguments:
cooperative_matrix2_supported(phys: VkPhysicalDevice ): bool

def cooperative_matrix2_supported (phys: VkPhysicalDevice) : bool

Arguments:
cooperative_matrix_supported(phys: VkPhysicalDevice ): bool

def cooperative_matrix_supported (phys: VkPhysicalDevice) : bool

Arguments:
cooperative_vector_supported(phys: VkPhysicalDevice ): bool

def cooperative_vector_supported (phys: VkPhysicalDevice) : bool

Arguments:
create_device_cooperative_matrix(phys: VkPhysicalDevice; queue_family: uint ): Device

def create_device_cooperative_matrix (phys: VkPhysicalDevice; queue_family: uint) : Device

Arguments:
create_device_coopmat_full_subgroups(phys: VkPhysicalDevice; queue_family: uint ): Device

def create_device_coopmat_full_subgroups (phys: VkPhysicalDevice; queue_family: uint) : Device

Arguments:

20.5.16.1. create_device_storage_8_16

create_device_storage_8_16(phys: VkPhysicalDevice; queue_family: uint ): Device

def create_device_storage_8_16 (phys: VkPhysicalDevice; queue_family: uint) : Device

Arguments:
create_device_storage_8_16(phys: VkPhysicalDevice; queue_family: uint; extensions: array<string> ): Device
create_device_storage_8_16_int_dot(phys: VkPhysicalDevice; queue_family: uint ): Device

def create_device_storage_8_16_int_dot (phys: VkPhysicalDevice; queue_family: uint) : Device

Arguments:
create_device_storage_8_16_int_dot_coopmat(phys: VkPhysicalDevice; queue_family: uint; transfer_family: int = -1 ): Device

def create_device_storage_8_16_int_dot_coopmat (phys: VkPhysicalDevice; queue_family: uint; transfer_family: int = -1) : Device

Arguments:
create_device_storage_8_16_int_dot_coopmat2(phys: VkPhysicalDevice; queue_family: uint; transfer_family: int = -1; decode_vector: bool = true ): Device

def create_device_storage_8_16_int_dot_coopmat2 (phys: VkPhysicalDevice; queue_family: uint; transfer_family: int = -1; decode_vector: bool = true) : Device

Arguments:

  • phys : VkPhysicalDevice

  • queue_family : uint

  • transfer_family : int

  • decode_vector : bool

external_memory_host_min_alignment(phys: VkPhysicalDevice ): uint64

def external_memory_host_min_alignment (phys: VkPhysicalDevice) : uint64

Arguments:
external_memory_host_supported(phys: VkPhysicalDevice ): bool

def external_memory_host_supported (phys: VkPhysicalDevice) : bool

Arguments:
integer_dot_product_supported(phys: VkPhysicalDevice ): bool

def integer_dot_product_supported (phys: VkPhysicalDevice) : bool

Arguments:
memory_priority_supported(phys: VkPhysicalDevice ): bool

def memory_priority_supported (phys: VkPhysicalDevice) : bool

Arguments:
select_transfer_queue_family(phys: VkPhysicalDevice ): int

def select_transfer_queue_family (phys: VkPhysicalDevice) : int

Arguments:
storage_8_16_supported(phys: VkPhysicalDevice ): bool

def storage_8_16_supported (phys: VkPhysicalDevice) : bool

Arguments:
subgroup_compute_ops_supported(phys: VkPhysicalDevice ): bool

def subgroup_compute_ops_supported (phys: VkPhysicalDevice) : bool

Arguments:
subgroup_properties(phys: VkPhysicalDevice ): VkPhysicalDeviceSubgroupProperties

def subgroup_properties (phys: VkPhysicalDevice) : VkPhysicalDeviceSubgroupProperties

Arguments:
timeline_semaphore_supported(phys: VkPhysicalDevice ): bool

def timeline_semaphore_supported (phys: VkPhysicalDevice) : bool

Arguments:

20.5.17. Pipeline introspection

dump_pipeline_executables(device: Device; pipeline: Pipeline ): string

def dump_pipeline_executables (device: Device; pipeline: Pipeline) : string

Arguments:
pipeline_exec_props_supported(phys: VkPhysicalDevice ): bool

def pipeline_exec_props_supported (phys: VkPhysicalDevice) : bool

Arguments:

20.5.18. Video memory budget

os_video_memory(phys: VkPhysicalDevice ): tuple<budget:uint64;usage:uint64;adapter_dedicated:uint64;adapter_shared:uint64>

def os_video_memory (phys: VkPhysicalDevice) : tuple<budget:uint64;usage:uint64;adapter_dedicated:uint64;adapter_shared:uint64>

Arguments: