VGF Encoder C++ API

The Encoder Application Program Interface is an offline tool that provides a set of API calls for creating VGF files. The API calls allow you to specify the inputs, outputs, resources and modules required to represent a model in the VGF format. The following example outlines the usage of the API calls to create an output VGF file.

Encoder Example Usage

After you create the encoder object, you can create resources for a given segment. The VGF Encoder stores these resources in a model resource table. Resources are defined for the segment inputs, outputs, and constants:

    std::unique_ptr<Encoder> encoder = CreateEncoder(pretendVulkanHeaderVersion);
    std::vector<int64_t> shape1{0, 1, 2, 3};
    std::vector<int64_t> strides1{4, 5, 6, 7};

    DescriptorType VK_DESCRIPTOR_TYPE_STORAGE_IMAGE = 3;
    FormatType VK_FORMAT_R4G4_UNORM_PACK8 = 1;
    ResourceRef resource0 =
        encoder->AddInputResource(VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, VK_FORMAT_R4G4_UNORM_PACK8, shape1, strides1);
    ResourceRef resource1 =
        encoder->AddOutputResource(VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, VK_FORMAT_R4G4_UNORM_PACK8, shape1, strides1);

For a constant resource, constant values are assigned to the created constant object. The resource reference is used to determine the index of the resource in the model resource table:

    FormatType VK_FORMAT_R4G4B4A4_UNORM_PACK16 = 12;
    std::vector<int64_t> shape2{8, 9, 10, 11};
    std::vector<int64_t> strides2{12, 13, 14, 15};
    ResourceRef resource2 = encoder->AddConstantResource(VK_FORMAT_R4G4B4A4_UNORM_PACK16, shape2, strides2);

Next, you can specify binding slots within the VGF. The assigned resources in the model resource table are then linked:

    BindingSlotRef inputBinding = encoder->AddBindingSlot(0, inputRef);
    BindingSlotRef outputBinding = encoder->AddBindingSlot(1, outputRef);

You can add descriptor set information, which is linked to each of the created binding slots:

    std::vector<BindingSlotRef> inputBindings = {inputBinding};
    std::vector<BindingSlotRef> outputBindings = {outputBinding};

    DescriptorSetInfoRef inputDescriptorRef = encoder->AddDescriptorSetInfo(inputBindings);
    DescriptorSetInfoRef outputDescriptorRef = encoder->AddDescriptorSetInfo(outputBindings);

    std::vector<DescriptorSetInfoRef> descriptorRefs = {inputDescriptorRef, outputDescriptorRef};

You must then specify the module for the segment, containing the SPIR-V™ module. This can also be done prior to adding resources:

    ModuleRef module = encoder->AddModule(ModuleType::GRAPH, "test_module", "entry_point", code);

Alternatively, you can add a placeholder module. The application provisions the SPIR-V™ binary data when the model is loaded.

    ModuleRef module = encoder->AddPlaceholderModule(ModuleType::GRAPH, "test_module", "entry_point");

If required, you can specify push constants for the segment:

    PushConstRangeRef pushConstRange = encoder->AddPushConstRange(1, 2, 3);
    std::vector<PushConstRangeRef> pushConstRanges = {pushConstRange};

    SegmentInfoRef segment =
        encoder->AddSegmentInfo(module, "test_segment", descriptorRefs, inputBindings, outputBindings);

You must repeat this process for multiple segments in the model. After creating each of the model segments, you must specify the sequencing based on the binding slots inputs and outputs:

    encoder->AddModelSequenceInputsOutputs(inputBindings, {"input"}, outputBindings, {"output"});

You must indicate the end of the encoding sequence. Then, you can write the VGF file representing the model:

    std::stringstream buffer;
    encoder->Finish();
    ASSERT_TRUE(encoder->WriteTo(buffer) == true);

Encoder API Reference

std::unique_ptr<Encoder> CreateEncoder(uint16_t vkHeaderVersion)

Create an Encoder object.

Parameters:: vkHeaderVersion -- Value of VK_HEADER_VERSION as defined in vulkan_core.h as included by the users code. This is necessary so that loaders of the VGF file know how to interpret “VkFormat” and “VkDescriptorType” enumeration types. A value of 0 (NOT RECOMMENDED) indicates that the VGF generating tool does not use the Vulkan definitions directly.
Returns:: Encoder object

class ModuleRef : public mlsdk::vgflib::Ref<ModuleRef>: #include <encoder.hpp>

Class to store reference to a Module.

class ResourceRef : public mlsdk::vgflib::Ref<ResourceRef>: #include <encoder.hpp>

Class to store reference to a Resource.

class ConstantRef : public mlsdk::vgflib::Ref<ConstantRef>: #include <encoder.hpp>

Class to store reference to a Constant.

class BindingSlotRef : public mlsdk::vgflib::Ref<BindingSlotRef>: #include <encoder.hpp>

Class to store reference to a Binding Slot.

class DescriptorSetInfoRef : public mlsdk::vgflib::Ref<DescriptorSetInfoRef>: #include <encoder.hpp>

Class to store reference to a Descriptor Set.

class SegmentInfoRef : public mlsdk::vgflib::Ref<SegmentInfoRef>: #include <encoder.hpp>

Class to store reference to Segment Info.

class PushConstRangeRef : public mlsdk::vgflib::Ref<PushConstRangeRef>: #include <encoder.hpp>

Class to store reference to a Push Constant Range.

class Encoder

#include <encoder.hpp>

Public Functions

virtual ~Encoder() = default: Destructor for the Encoder class.

virtual ModuleRef AddModule(ModuleType type, const std::string &name, const std::string &entryPoint, const std::vector<uint32_t> &code = {}) = 0

Adds a module, with code, to the VGF.

Parameters:

type -- The type of the module
name -- Unique string name of the module
entryPoint -- Entry point into the shader e.g. “main”
code -- Vector of uint32 representing SPIR-V byte code

Returns:

ModuleRef Type containing information for the added module

virtual ModuleRef AddPlaceholderModule(ModuleType type, const std::string &name, const std::string &entryPoint) = 0

Adds a placeholder module to the VGF where the code will be provisioned at load/decode time.

Parameters:

type -- The type of the module
name -- Unique string name of the module
entryPoint -- Entry point into the shader e.g. “main”

Returns:

ModuleRef Type containing information for the added module

virtual ResourceRef AddInputResource(DescriptorType descriptorType, FormatType vkFormat, const std::vector<int64_t> &shape, const std::vector<int64_t> &strides) = 0

Add an INPUT resource to the model resource table.

Parameters:

descriptorType -- The module type of the resource table
vkFormat -- VkFormat of the resource data
shape -- Vector representation of the resource shape. “-1” values represent an unshaped dimension
strides -- Vector representation of the resource stride. An empty strides is assumed packed layout

Returns:

ResourceRef type containing information for the added table entry

virtual ResourceRef AddOutputResource(DescriptorType descriptorType, FormatType vkFormat, const std::vector<int64_t> &shape, const std::vector<int64_t> &strides) = 0

Add an OUTPUT resource to the model resource table.

Parameters:

descriptorType -- The module type of the resource table
vkFormat -- VkFormat of the resource data
shape -- Vector representation of the resource shape. “-1” values represent an unshaped dimension
strides -- Vector representation of the resource stride. An empty strides is assumed packed layout

Returns:

ResourceRef type containing information for the added table entry

virtual ResourceRef AddIntermediateResource(DescriptorType descriptorType, FormatType vkFormat, const std::vector<int64_t> &shape, const std::vector<int64_t> &strides) = 0

Add an INTERMEDIATE resource to the model resource table.

Parameters:

descriptorType -- The module type of the resource table
vkFormat -- VkFormat of the resource data
shape -- Vector representation of the resource shape. “-1” values represent an unshaped dimension
strides -- Vector representation of the resource stride. An empty strides is assumed packed layout

Returns:

ResourceRef type containing information for the added table entry

virtual ResourceRef AddConstantResource(FormatType vkFormat, const std::vector<int64_t> &shape, const std::vector<int64_t> &strides) = 0

Add a CONSTANT tensor to the model resource table.

Parameters:

vkFormat -- VkFormat of the resource data
shape -- Vector representation of the resource shape. “-1” values represent an unshaped dimension
strides -- Vector representation of the resource stride. An empty strides is assumed packed layout

Returns:

ResourceRef type containing information for the added table entry

virtual ConstantRef AddConstant(ResourceRef resource, const void *data, size_t sizeInBytes, int64_t sparsityDimension = -1) = 0

Add constant values to a constant resource type in the model resource table.

Parameters:

resource -- Resource reference used in model resource table
data -- Pointer to the memory containing the constant data
sizeInBytes -- Size of the constant data to encode
sparsityDimension -- Dimension on which the constant is sparse

Returns:

ConstantRef type containing information for the added constant

virtual BindingSlotRef AddBindingSlot(uint32_t binding, ResourceRef resource) = 0

Add a binding slot and associate to resource in the model resource table.

Parameters:

binding -- The binding slot to be added
resource -- Ref to resource in model resource table

Returns:

BindingSlotRef type containing information for the added binding slot

virtual DescriptorSetInfoRef AddDescriptorSetInfo(const std::vector<BindingSlotRef> &bindings = {}) = 0

Add descriptor set info for bindings.

Parameters:: bindings -- Vector of binding slot references
Returns:: DescriptorSetInfoRef type containing information for the added descriptor set

virtual PushConstRangeRef AddPushConstRange(uint32_t stageFlags, uint32_t offset, uint32_t size) = 0

Add push constant range to segment info.

Parameters:

stageFlags -- Stage flags describing the shader stages
offset -- Start offset in units of bytes and must be a multiple of 4
size -- Start size in units of bytes and must be a multiple of 4

Returns:

PushConstRangeRef type containing information for the added push constant range

virtual SegmentInfoRef AddSegmentInfo(ModuleRef module, const std::string &name, const std::vector<DescriptorSetInfoRef> &descriptors = {}, const std::vector<BindingSlotRef> &inputs = {}, const std::vector<BindingSlotRef> &outputs = {}, const std::vector<ConstantRef> &constants = {}, const std::array<uint32_t, 3> &dispatchShape = {}, const std::vector<PushConstRangeRef> &pushConstRanges = {}) = 0

Add segment info with approprate references.

Parameters:

module -- Module reference of the added module
name -- Unique string name of the segment
descriptors -- Vector of references to descriptor set info
inputs -- Vector of references to binding slots used as inputs
outputs -- Vector of references to binding slots used as outputs
constants -- Vector of references to segment constants
dispatchShape -- 3-dimensional array of dispatch shape
pushConstRanges -- Vector of references to segment push constant ranges

Returns:

SegmentInfoRef type containing information for the added push constant range

virtual void AddModelSequenceInputsOutputs(const std::vector<BindingSlotRef> &inputs = {}, const std::vector<std::string> &inputNames = {}, const std::vector<BindingSlotRef> &outputs = {}, const std::vector<std::string> &outputNames = {}) = 0

Add the sequence of inputs and outputs to the model.

Parameters:

inputs -- Vector of BindingSlotRefs used as inputs to the model
inputNames -- Vector of std::string containing the names corresponding to inputs. inputNames must be empty or equal inputs.size()
outputs -- Vector of BindingSlotRefs used as outputs to the model
outputNames -- Vector of std::string containing the names corresponding to outputs. outputNames must be empty or equal outputs.size()

virtual void Finish() = 0: Inidicate the finishing of VGF file encoding.

virtual bool WriteTo(std::ostream &output) = 0

Write the output VGF file.

Parameters:: output -- Output destination of the .vgf file
Returns:: Bool True if write successful