Libraries.Game.Graphics.Vulkan.VulkanPipelineInfoCreator Documentation

This is a helper class that is used to create VulkanPipelineInfo objects for initializing VulkanPipelines. This class makes it easier to add vertex data, and automatically calculates both Vulkan offsets as well as the vertex offets in Quorum (used to find elements in the structure of a DrawableShape, for example). Most commonly, this class is used as part of a VulkanShaderMapping to create a program's pipeline info.

Example Code

package Libraries.Game.Graphics.Shaders.Vulkan.Mapping

use Libraries.Game.Graphics.Shaders.Vulkan.VulkanShaderProgram
use Libraries.Game.Graphics.Vulkan.all
use Libraries.Game.Graphics.Shaders.Programs.ShaderProgram
use Libraries.Game.Graphics.Drawable
use Libraries.Game.Graphics.DrawableShape
use Libraries.Game.GameStateManager
use Libraries.Game.Graphics.Camera
use Libraries.Game.Graphics.Vulkan.Commands.BindDescriptorSetCommand

class ExampleShaderMapping is VulkanShaderMapping

// This is the index of the added vertex inputs within a DrawableShape.
integer myVertexInputIndex1 = 0
integer myVertexInputIndex2 = 0

// Resources for a descriptor used by the pipeline. Used to set a uniform buffer in the fragment shader.
VulkanBuffer uniformBuffer
VulkanNumber32BitMappedMemory uniformBufferMemory = undefined
VulkanDescriptorSet uniformDescriptorSet = undefined
VulkanPipelineLayout pipelineLayout = undefined

on create
    // The info creator will add the default 2D resources, 
    // so we add this command so the ShaderMapping will automatically receive these resources from the Painter2D during drawing.
    UseDefaultResources2D(true)
end

// Returns the size of each vertex in the DrawableShape (which stores values as numbers).
// This will be the index of the last added vertex input, plus its size in the data structure.
action GetVertexSize returns integer
    return myVertexInputIndex2 + 1
end

// This action is used to setup the values of a VulkanPipelineInfo that will be used to create the
// VulkanPipeline needed for the shader program. This can also be used to create and keep copies of
// any Vulkan resources that will be needed to send or change shader data.
action CreatePipelineInfo(VulkanShaderProgram program, VulkanDevice device) returns VulkanPipelineInfo
    VulkanConstants constants

    // Make the info creator, start it, and add the default vertex inputs and descriptors for 2D shader programs in the game engine.
    VulkanPipelineInfoCreator creator
    creator:Begin(device)
    creator:AddDefaultInfo2D()
    
    // Add an extra vertex input. This one is a Vulkan 32-bit signed float. 
    // The returned index is the offset into a Quorum DrawableShape where this input will be placed.
    myVertexInputIndex1 = creator:AddVertexInput(constants:FORMAT_R32_SFLOAT)
    // The second input is a 32-bit unsigned integer.
    myVertexInputIndex2 = creator:AddVertexInput(constants:FORMAT_R32_UINT)
    
    // Add a binding for a uniform buffer that will be accessible in the program's fragment shader.
    creator:AddDescriptorSetLayoutBinding(constants:SHADER_STAGE_FRAGMENT_BIT, constants:DESCRIPTOR_TYPE_UNIFORM_BUFFER)
    VulkanDescriptorSetLayout descriptorLayout = creator:FinishDescriptorSetLayout()
    
    // Create a uniform buffer for a 3x3 matrix, where each value is 4 bytes large (i.e. 9 32-bit floats).
    uniformBuffer:CreateMappableBuffer(device, 3 * 3 * 4, constants:BUFFER_USAGE_UNIFORM_BUFFER_BIT)
    uniformBufferMemory = uniformBuffer:MapToNumber32BitMemory()
    
    // Indicate which buffer will be used for the descriptor, and the start and end index of that buffer to read from.
    VulkanDescriptorResourcesInfo bufferResourcesInfo
    bufferResourcesInfo:SetDescriptorType(constants:DESCRIPTOR_TYPE_UNIFORM_BUFFER)
    bufferResourcesInfo:AddBufferInfo(uniformBuffer, 0, uniformBuffer:GetSize())

    // Use the DescriptorSetManager from the game's graphics system to create the descriptor, using the layout we made with the Creator.
    GameStateManager gameState
    VulkanGraphics graphics = cast(VulkanGraphics, gameState:GetGameGraphics())
    VulkanDescriptorSetManager descriptorManager = graphics:GetDescriptorSetManager()
    uniformDescriptorSet = descriptorManager:CreateDescriptorSet(descriptorLayout, bufferResourcesInfo)
    
    // Finish creating the PipelineInfo, then store the created PipelineLayout so we can use it later.
    VulkanPipelineInfo info = creator:Finish()
    pipelineLayout = info:GetLayout()
    return info
end

// This action is used to update the vertex information sent from Quorum to the vertex shader.
action SetVertexData(ShaderProgram program, Drawable drawable, DrawableShape shape)
    // Set any vertex input information here, using the indices the creator returned for us.
    shape:SetDataForAllVertices(myVertexInputIndex1, 3.14)
    shape:SetDataForAllVertices(myVertexInputIndex2, 1)
end

// This action is called when the shader program will begin rendering.
action Begin(ShaderProgram program, Camera camera, VulkanCommandBuffer commandBuffer, integer swapchainIndex)
    // Update the mapped data, if needed. In this case, we're setting a 3x3 matrix with dummy values.
    integer counter = 0 
    repeat while counter < uniformBufferMemory:GetSize()
        uniformBufferMemory:Set(counter, counter * 2)
        counter = counter + 1
    end

    // Send a command to bind our descriptors. This will make our mapped descriptor data available in the shaders.
    //Because default 2D resources uses set indices 0 and 1, our descriptor set must be bound to set index = 2.        
    BindDescriptorSetCommand descriptorBind
    descriptorBind:SetPipelineLayout(pipelineLayout)
    descriptorBind:SetDescriptorSet(uniformDescriptorSet)
    descriptorBind:SetSetIndex(2)
    commandBuffer:Record(descriptorBind)
end

end

Inherits from: Libraries.Language.Object

Actions Documentation

AddColorBlendAttachmentState(Libraries.Game.Graphics.Vulkan.VulkanPipelineColorBlendAttachmentState colorBlend)

This action adds the provided VulkanPipelineColorBlendAttachmentState as a blending value to the PipelineInfo.

Parameters

AddDefaultInfo2D()

This action adds default resources to the PipelineInfo, allowing it to use the default information provided by a VulkanPainter2D. More specifically, it adds these vertex inputs: - X, Y, Z position coordinates, as a Vector3 of 32-bit signed floating point values. - RGBA vertex colors, as a Vector4 of 8-bit values normalized between 0 and 1. - Texture (U, V) coordinates, stored as a Vector2 of 32-bit signed floating point values. - A texture index value, stored as a 32-bit unsigned integer. It also adds a transparency-enabled color blend attachment and dynamic scissor and viewport states. Finally, it adds descriptor layouts for the default 2D camera, sampler, and global textures. If using these values, this action should be called before adding additional vertex inputs or descriptors. If using this inside a VulkanShaderMapping, that mapping should also call "UseDefaultResources2D(true)".

AddDefaultInfo3D()

Create a binding for a sampler to use during fragment shading, then add the sampler to the returned binding.

AddDescriptorSetLayout(Libraries.Game.Graphics.Vulkan.VulkanDescriptorSetLayout layout)

This action adds an already created VulkanDescriptorSetLayout to the info. This can be used to share descriptor set layouts across different pipelines. If any bindings have been individually added to the Creator, this will automatically finalize them into a separate layout, as if using FinishDescriptorSetLayout, before adding the new layout to the Creator.

Parameters

AddDescriptorSetLayoutBinding(integer stageFlags, integer type)

This action adds a new VulkanDescriptorSetLayoutBinding to the creator's current DescriptorSetLayout, which will be available in the given shader stages and will have the provided type. The binding's index will be automatically set to the next binding in the layout (i.e., 0, then 1, then 2, etc.) If the creator doesn't have a DescriptorSetLayout yet, this will automatically make one and insert the binding.

Parameters

  • integer stageFlags: A combination of 1 or more Vulkan SHADER_STAGE flags, combined using bitwise OR or addition, indicating which shader stages the descriptor will be available in.
  • integer type: A Vulkan DESCRIPTOR_TYPE value from the VulkanConstants class.

Return

Libraries.Game.Graphics.Vulkan.VulkanDescriptorSetLayoutBinding:

AddDescriptorSetLayoutBinding(Libraries.Game.Graphics.Vulkan.VulkanDescriptorSetLayoutBinding binding)

This action adds a VulkanDescriptorSetLayoutBinding to the creator's current DescriptorSetLayout. The binding's index will be automatically set to the next binding in the layout (i.e., 0, then 1, then 2, etc.) If the creator doesn't have a DescriptorSetLayout yet, this will automatically make one and insert the binding.

Parameters

AddDynamicScissor()

This action adds the DYNAMIC_STATE_SCISSOR flag to the VulkanPipelineInfo, indicating that scissor values can change while the pipeline is active.

AddDynamicState(integer dynamicState)

This action adds a dynamic state flag to the VulkanPipelineInfo. This will signal that certain parameters can change while the pipeline is active.

Parameters

  • integer dynamicState: A Vulkan DYNAMIC_STATE flag from the VulkanConstants class.

AddDynamicViewport()

This action adds the DYNAMIC_STATE_VIEWPORT flag to the VulkanPipelineInfo, indicating that the viewport can change while the pipeline is active.

AddOpaqueColorBlendAttachmentState()

This action adds a default VulkanPipelineColorBlendAttachmentState with NO transparency to the PipelineInfo.

AddTransparentColorBlendAttachmentState()

This action adds a default VulkanPipelineColorBlendAttachmentState with transparency to the PipelineInfo.

AddVertexInput(integer vulkanFormat)

This action adds a new vertex input to the current set, using the given data format. Internally, this creates a new VulkanVertexInputAttributeDescription, where the binding and attribute indices are automatically incremented and the offset is calculated. This action also returns an index that corresponds to this input's location within a Quorum DrawableShape. This index can be used with a DrawableShape to set this input's data in a ShaderMapping.

Parameters

  • integer vulkanFormat: A Vulkan FORMAT value from the VulkanConstants class, describing the data type of the input.

Return

integer: An index to where the value will be expected within a Quorum DrawableShape.

Begin(Libraries.Game.Graphics.Vulkan.VulkanDevice device)

This action begins creating a new VulkanPipelineInfo. This action must be called before using other actions to add elements to the info.

Parameters

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns an integer. The result is larger if this hash code is larger than the object passed as a parameter, smaller, or equal. In this case, -1 means smaller, 0 means equal, and 1 means larger. This action was changed in Quorum 7 to return an integer, instead of a CompareResult object, because the previous implementation was causing efficiency issues.

Parameters

Return

integer: The Compare result, Smaller, Equal, or Larger.

Example

Object o
Object t
integer result = o:Compare(t) //1 (larger), 0 (equal), or -1 (smaller)

Equals(Libraries.Language.Object object)

This action determines if two objects are equal based on their hash code values.

Parameters

Return

boolean: True if the hash codes are equal and false if they are not equal.

Example

use Libraries.Language.Object
use Libraries.Language.Types.Text
Object o
Text t
boolean result = o:Equals(t)

Finish()

This action finishes PipelineInfo creation. This action returns the created info, which will be ready for use, and resets any state in the creator. After calling Finish, other actions can't be called on the Creator unless the Begin action is called again first.

Return

Libraries.Game.Graphics.Vulkan.VulkanPipelineInfo: The created VulkanPipelineInfo.

FinishDescriptorSetLayout()

This action finalizes any previously added DescriptorSetLayoutBindings and creates a VulkanDescriptorSetLayout. While this action is called automatically when Finish is called, users may want to manually call this action before Finish if they need the VulkanDescriptorSetLayout (e.g., to bind descriptor sets later).

Return

Libraries.Game.Graphics.Vulkan.VulkanDescriptorSetLayout: A VulkanDescriptorSetLayout containing all of the currently added descriptor bindings.

GetHashCode()

This action gets the hash code for an object.

Return

integer: The integer hash code of the object.

Example

Object o
integer hash = o:GetHashCode()

NewInstanceRateVertexInputBinding()

This action creates a new vertex input binding, and sets its binding rate to per-instance. The new binding will be empty and will not include any previously added vertex inputs. Previously added inputs will be in their own binding. This function is only needed if you have more than one set of vertex inputs for the pipeline. Most pipelines only need one set of vertex inputs, so this action isn't needed.

NewVertexInputBinding(integer vulkanVertexRate)

This action creates a new vertex input binding, and sets its binding rate to the requested rate. The new binding will be empty and will not include any previously added vertex inputs. Previously added inputs will be in their own binding. This function is only needed if you have more than one set of vertex inputs for the pipeline. Most pipelines only need one set of vertex inputs, so this action isn't needed.

Parameters

  • integer vulkanVertexRate: A VERTEX_INPUT_RATE value from the VulkanConstants class, indicating how the vertex inputs will be used.

NewVertexRateVertexInputBinding()

This action creates a new vertex input binding, and sets its binding rate to per-vertex. The new binding will be empty and will not include any previously added vertex inputs. Previously added inputs will be in their own binding. This function is only needed if you have more than one set of vertex inputs for the pipeline. Most pipelines only need one set of vertex inputs, so this action isn't needed.

SetPushConstantRange(Libraries.Game.Graphics.Vulkan.VulkanPushConstantRange pushConstantRange)

For default 3D usage, the push constants need to store 8 bytes for a single 64-bit buffer pointer.

Parameters