VGF Encoder C API

The Encoder C API is a thin C wrapper over the C++ VGF Encoder API. It allows C callers to create VGF files by adding modules, resources, resource alias groups, sampler metadata, constants, binding slots, descriptor set information, segments, model inputs and model outputs.

The API owns an encoder object returned by mlsdk_encoder_create. Destroy the encoder with mlsdk_encoder_destroy. After all entries have been added, call mlsdk_encoder_finish and then mlsdk_encoder_write_to_file.

C Encoder API Reference

enum mlsdk_encoder_module_type

Module type encoded in a VGF module table entry and model sequence segment.

Values:

enumerator mlsdk_encoder_module_type_compute

Compute pipeline module.

enumerator mlsdk_encoder_module_type_graph

Graph pipeline module.

enum mlsdk_encoder_shader_type

Source language for non-SPIR-V shader modules.

Values:

enumerator mlsdk_encoder_shader_type_glsl

GLSL source module.

enumerator mlsdk_encoder_shader_type_hlsl

HLSL source module.

typedef uint16_t mlsdk_encoder_vk_header_version

Type for VK_HEADER_VERSION.

typedef int32_t mlsdk_encoder_vk_descriptor_type

Type for a VkDescriptorType enum value.

typedef int32_t mlsdk_encoder_vk_format

Type for a VkFormat enum value.

typedef uint32_t mlsdk_encoder_alias_group_id

Type for model resource alias group ids.

mlsdk_encoder *mlsdk_encoder_create(mlsdk_encoder_vk_header_version vkHeaderVersion)

Creates a VGF encoder.

Parameters:

  • vkHeaderVersion -- Value of VK_HEADER_VERSION used when encoding the VGF.

Returns:

Encoder handle. Destroy with mlsdk_encoder_destroy.

void mlsdk_encoder_destroy(mlsdk_encoder *encoder)

Destroys a VGF encoder.

Parameters:

  • encoder -- Encoder handle returned by mlsdk_encoder_create. Passing nullptr is allowed.

mlsdk_encoder_module_ref mlsdk_encoder_add_spirv_module(mlsdk_encoder *encoder, mlsdk_encoder_module_type type, const char *name, const char *entryPoint, const uint32_t *code, size_t numWords)

Adds a SPIR-V module to the VGF.

Parameters:

  • encoder -- Encoder handle.

  • type -- Module type.

  • name -- Module name.

  • entryPoint -- Module entry point.

  • code -- Pointer to SPIR-V words. May be nullptr when numWords is zero for a placeholder module.

  • numWords -- Number of SPIR-V words.

Returns:

Reference to the added module.

mlsdk_encoder_module_ref mlsdk_encoder_add_source_module(mlsdk_encoder *encoder, mlsdk_encoder_module_type type, const char *name, const char *entryPoint, mlsdk_encoder_shader_type shaderType, const char *code)

Adds a source-code module to the VGF.

Parameters:

  • encoder -- Encoder handle.

  • type -- Module type.

  • name -- Module name.

  • entryPoint -- Module entry point.

  • shaderType -- Shader source language.

  • code -- Null-terminated shader source. May be nullptr for an empty module.

Returns:

Reference to the added module.

mlsdk_encoder_resource_ref mlsdk_encoder_add_input_resource(mlsdk_encoder *encoder, mlsdk_encoder_vk_descriptor_type vkDescriptorType, mlsdk_encoder_vk_format vkFormat, const int64_t *shape, size_t shapeSize, const int64_t *strides, size_t stridesSize)

Adds an input resource to the model resource table.

Parameters:

  • encoder -- Encoder handle.

  • vkDescriptorType -- VkDescriptorType value for this resource.

  • vkFormat -- VkFormat value for this resource.

  • shape -- Pointer to tensor shape dimensions. May be nullptr when shapeSize is zero.

  • shapeSize -- Number of shape dimensions.

  • strides -- Pointer to tensor stride dimensions. May be nullptr when stridesSize is zero.

  • stridesSize -- Number of stride dimensions.

Returns:

Reference to the added resource.

mlsdk_encoder_resource_ref mlsdk_encoder_add_input_resource_with_alias_group(mlsdk_encoder *encoder, mlsdk_encoder_vk_descriptor_type vkDescriptorType, mlsdk_encoder_vk_format vkFormat, const int64_t *shape, size_t shapeSize, const int64_t *strides, size_t stridesSize, mlsdk_encoder_alias_group_id aliasGroupId)

Adds an input resource with an alias group to the model resource table.

Parameters:

  • encoder -- Encoder handle.

  • vkDescriptorType -- VkDescriptorType value for this resource.

  • vkFormat -- VkFormat value for this resource.

  • shape -- Pointer to tensor shape dimensions. May be nullptr when shapeSize is zero.

  • shapeSize -- Number of shape dimensions.

  • strides -- Pointer to tensor stride dimensions. May be nullptr when stridesSize is zero.

  • stridesSize -- Number of stride dimensions.

  • aliasGroupId -- Alias group shared with peer model resource table entries.

Returns:

Reference to the added resource.

mlsdk_encoder_resource_ref mlsdk_encoder_add_output_resource(mlsdk_encoder *encoder, mlsdk_encoder_vk_descriptor_type vkDescriptorType, mlsdk_encoder_vk_format vkFormat, const int64_t *shape, size_t shapeSize, const int64_t *strides, size_t stridesSize)

Adds an output resource to the model resource table.

Parameters:

  • encoder -- Encoder handle.

  • vkDescriptorType -- VkDescriptorType value for this resource.

  • vkFormat -- VkFormat value for this resource.

  • shape -- Pointer to tensor shape dimensions. May be nullptr when shapeSize is zero.

  • shapeSize -- Number of shape dimensions.

  • strides -- Pointer to tensor stride dimensions. May be nullptr when stridesSize is zero.

  • stridesSize -- Number of stride dimensions.

Returns:

Reference to the added resource.

mlsdk_encoder_resource_ref mlsdk_encoder_add_output_resource_with_alias_group(mlsdk_encoder *encoder, mlsdk_encoder_vk_descriptor_type vkDescriptorType, mlsdk_encoder_vk_format vkFormat, const int64_t *shape, size_t shapeSize, const int64_t *strides, size_t stridesSize, mlsdk_encoder_alias_group_id aliasGroupId)

Adds an output resource with an alias group to the model resource table.

Parameters:

  • encoder -- Encoder handle.

  • vkDescriptorType -- VkDescriptorType value for this resource.

  • vkFormat -- VkFormat value for this resource.

  • shape -- Pointer to tensor shape dimensions. May be nullptr when shapeSize is zero.

  • shapeSize -- Number of shape dimensions.

  • strides -- Pointer to tensor stride dimensions. May be nullptr when stridesSize is zero.

  • stridesSize -- Number of stride dimensions.

  • aliasGroupId -- Alias group shared with peer model resource table entries.

Returns:

Reference to the added resource.

mlsdk_encoder_resource_ref mlsdk_encoder_add_intermediate_resource(mlsdk_encoder *encoder, mlsdk_encoder_vk_descriptor_type vkDescriptorType, mlsdk_encoder_vk_format vkFormat, const int64_t *shape, size_t shapeSize, const int64_t *strides, size_t stridesSize)

Adds an intermediate resource to the model resource table.

Parameters:

  • encoder -- Encoder handle.

  • vkDescriptorType -- VkDescriptorType value for this resource.

  • vkFormat -- VkFormat value for this resource.

  • shape -- Pointer to tensor shape dimensions. May be nullptr when shapeSize is zero.

  • shapeSize -- Number of shape dimensions.

  • strides -- Pointer to tensor stride dimensions. May be nullptr when stridesSize is zero.

  • stridesSize -- Number of stride dimensions.

Returns:

Reference to the added resource.

mlsdk_encoder_resource_ref mlsdk_encoder_add_intermediate_resource_with_alias_group(mlsdk_encoder *encoder, mlsdk_encoder_vk_descriptor_type vkDescriptorType, mlsdk_encoder_vk_format vkFormat, const int64_t *shape, size_t shapeSize, const int64_t *strides, size_t stridesSize, mlsdk_encoder_alias_group_id aliasGroupId)

Adds an intermediate resource with an alias group to the model resource table.

Parameters:

  • encoder -- Encoder handle.

  • vkDescriptorType -- VkDescriptorType value for this resource.

  • vkFormat -- VkFormat value for this resource.

  • shape -- Pointer to tensor shape dimensions. May be nullptr when shapeSize is zero.

  • shapeSize -- Number of shape dimensions.

  • strides -- Pointer to tensor stride dimensions. May be nullptr when stridesSize is zero.

  • stridesSize -- Number of stride dimensions.

  • aliasGroupId -- Alias group shared with peer model resource table entries.

Returns:

Reference to the added resource.

mlsdk_encoder_resource_ref mlsdk_encoder_add_constant_resource(mlsdk_encoder *encoder, mlsdk_encoder_vk_format vkFormat, const int64_t *shape, size_t shapeSize, const int64_t *strides, size_t stridesSize)

Adds a constant resource to the model resource table.

Parameters:

  • encoder -- Encoder handle.

  • vkFormat -- VkFormat value for this resource.

  • shape -- Pointer to tensor shape dimensions. May be nullptr when shapeSize is zero.

  • shapeSize -- Number of shape dimensions.

  • strides -- Pointer to tensor stride dimensions. May be nullptr when stridesSize is zero.

  • stridesSize -- Number of stride dimensions.

Returns:

Reference to the added resource.

void mlsdk_encoder_add_sampler_config(mlsdk_encoder *encoder, mlsdk_encoder_resource_ref resource, uint32_t samplerMinFilter, uint32_t samplerMagFilter, uint32_t samplerAddressModeU, uint32_t samplerAddressModeV, uint32_t samplerBorderColor)

Sets sampler metadata for an existing model resource table entry.

Parameters:

  • encoder -- Encoder handle.

  • resource -- Reference to the resource to update.

  • samplerMinFilter -- VkFilter value used for minification.

  • samplerMagFilter -- VkFilter value used for magnification.

  • samplerAddressModeU -- VkSamplerAddressMode for the U axis.

  • samplerAddressModeV -- VkSamplerAddressMode for the V axis.

  • samplerBorderColor -- VkBorderColor value.

void mlsdk_encoder_set_alias_group(mlsdk_encoder *encoder, mlsdk_encoder_resource_ref resource, mlsdk_encoder_alias_group_id aliasGroupId)

Assigns an alias group to an existing non-constant model resource table entry.

Parameters:

  • encoder -- Encoder handle.

  • resource -- Reference to the resource to update.

  • aliasGroupId -- Alias group shared with peer model resource table entries.

mlsdk_encoder_constant_ref mlsdk_encoder_add_constant(mlsdk_encoder *encoder, mlsdk_encoder_resource_ref resource, const void *data, size_t sizeInBytes, int64_t sparsityDimension)

Adds constant bytes for a constant resource.

Parameters:

  • encoder -- Encoder handle.

  • resource -- Reference to a constant resource in the model resource table.

  • data -- Pointer to constant data bytes.

  • sizeInBytes -- Size of constant data in bytes.

  • sparsityDimension -- Sparse dimension, or MLSDK_ENCODER_CONSTANT_NOT_SPARSE_DIMENSION for non-sparse constants.

Returns:

Reference to the added constant.

mlsdk_encoder_binding_slot_ref mlsdk_encoder_add_binding_slot(mlsdk_encoder *encoder, uint32_t binding, mlsdk_encoder_resource_ref resource)

Adds a binding slot associated with a model resource table entry.

Parameters:

  • encoder -- Encoder handle.

  • binding -- Binding number exposed to the shader.

  • resource -- Reference to the resource bound at this slot.

Returns:

Reference to the added binding slot.

mlsdk_encoder_descriptor_set_info_ref mlsdk_encoder_add_descriptor_set_info(mlsdk_encoder *encoder, const mlsdk_encoder_binding_slot_ref *bindings, size_t numBindings, uint32_t setIndex)

Adds descriptor set information for a group of binding slots.

Parameters:

  • encoder -- Encoder handle.

  • bindings -- Pointer to binding slot references. May be nullptr when numBindings is zero.

  • numBindings -- Number of binding slot references.

  • setIndex -- Explicit descriptor set index, or MLSDK_ENCODER_DESCRIPTOR_SET_INDEX_UNSPECIFIED to use legacy positional semantics.

Returns:

Reference to the added descriptor set info.

mlsdk_encoder_push_const_range_ref mlsdk_encoder_add_push_const_range(mlsdk_encoder *encoder, uint32_t stageFlags, uint32_t offset, uint32_t size)

Adds a push constant range.

Parameters:

  • encoder -- Encoder handle.

  • stageFlags -- Shader stage flags for the range.

  • offset -- Start offset in bytes.

  • size -- Size in bytes.

Returns:

Reference to the added push constant range.

mlsdk_encoder_segment_info_ref mlsdk_encoder_add_segment_info(mlsdk_encoder *encoder, mlsdk_encoder_module_ref module, const char *name, const mlsdk_encoder_descriptor_set_info_ref *descriptors, size_t numDescriptors, const mlsdk_encoder_binding_slot_ref *inputs, size_t numInputs, const mlsdk_encoder_binding_slot_ref *outputs, size_t numOutputs, const mlsdk_encoder_constant_ref *constants, size_t numConstants, const uint32_t dispatchShape[3], const mlsdk_encoder_push_const_range_ref *pushConstRanges, size_t numPushConstRanges)

Adds a model sequence segment.

Parameters:

  • encoder -- Encoder handle.

  • module -- Module used by this segment.

  • name -- Segment name.

  • descriptors -- Pointer to descriptor set info references. May be nullptr when numDescriptors is zero.

  • numDescriptors -- Number of descriptor set info references.

  • inputs -- Pointer to segment input binding slot references. May be nullptr when numInputs is zero.

  • numInputs -- Number of input binding slot references.

  • outputs -- Pointer to segment output binding slot references. May be nullptr when numOutputs is zero.

  • numOutputs -- Number of output binding slot references.

  • constants -- Pointer to segment constant references. May be nullptr when numConstants is zero.

  • numConstants -- Number of constant references.

  • dispatchShape -- Three-dimensional dispatch shape. Passing nullptr encodes {0, 0, 0}.

  • pushConstRanges -- Pointer to push constant range references. May be nullptr when numPushConstRanges is zero.

  • numPushConstRanges -- Number of push constant range references.

Returns:

Reference to the added segment.

void mlsdk_encoder_add_model_sequence_inputs_outputs(mlsdk_encoder *encoder, const mlsdk_encoder_binding_slot_ref *inputs, size_t numInputs, const char **inputNames, size_t numInputNames, const mlsdk_encoder_binding_slot_ref *outputs, size_t numOutputs, const char **outputNames, size_t numOutputNames)

Adds model-level input and output binding slot sequences.

Parameters:

  • encoder -- Encoder handle.

  • inputs -- Pointer to model input binding slot references. May be nullptr when numInputs is zero.

  • numInputs -- Number of model input binding slot references.

  • inputNames -- Pointer to null-terminated input names. May be nullptr when numInputNames is zero.

  • numInputNames -- Number of input names. Must be zero or equal to numInputs.

  • outputs -- Pointer to model output binding slot references. May be nullptr when numOutputs is zero.

  • numOutputs -- Number of model output binding slot references.

  • outputNames -- Pointer to null-terminated output names. May be nullptr when numOutputNames is zero.

  • numOutputNames -- Number of output names. Must be zero or equal to numOutputs.

void mlsdk_encoder_finish(mlsdk_encoder *encoder)

Finishes encoding after all VGF contents have been added.

Parameters:

  • encoder -- Encoder handle.

bool mlsdk_encoder_write_to_file(mlsdk_encoder *encoder, const char *path)

Writes a finished VGF encoder to a file.

Parameters:

  • encoder -- Encoder handle.

  • path -- Output file path.

Returns:

true when writing succeeded, false otherwise.

struct mlsdk_encoder_module_ref
#include </home/svc_ngp/workspace/VulkanGithubPagesNightly/build/vgf-lib/docs/sources/include-c/vgf/encoder.h>

Reference to an encoded module table entry.

struct mlsdk_encoder_resource_ref
#include </home/svc_ngp/workspace/VulkanGithubPagesNightly/build/vgf-lib/docs/sources/include-c/vgf/encoder.h>

Reference to an encoded model resource table entry.

struct mlsdk_encoder_constant_ref
#include </home/svc_ngp/workspace/VulkanGithubPagesNightly/build/vgf-lib/docs/sources/include-c/vgf/encoder.h>

Reference to an encoded constant table entry.

struct mlsdk_encoder_binding_slot_ref
#include </home/svc_ngp/workspace/VulkanGithubPagesNightly/build/vgf-lib/docs/sources/include-c/vgf/encoder.h>

Reference to an encoded binding slot entry.

struct mlsdk_encoder_descriptor_set_info_ref
#include </home/svc_ngp/workspace/VulkanGithubPagesNightly/build/vgf-lib/docs/sources/include-c/vgf/encoder.h>

Reference to an encoded descriptor set info entry.

struct mlsdk_encoder_segment_info_ref
#include </home/svc_ngp/workspace/VulkanGithubPagesNightly/build/vgf-lib/docs/sources/include-c/vgf/encoder.h>

Reference to an encoded segment info entry.

struct mlsdk_encoder_push_const_range_ref
#include </home/svc_ngp/workspace/VulkanGithubPagesNightly/build/vgf-lib/docs/sources/include-c/vgf/encoder.h>

Reference to an encoded push constant range entry.