Render

Api for render specific data

Namespace: dmRender
Include: #include <>
TYPES
HConstant Shader constant handle
HFont Font map handle
HMaterial Material instance handle
HNamedConstantBuffer Shader constant buffer handle. Holds name and valu...
HRenderContext The render context
HRenderListDispatch Render dispatch function handle.
RenderListDispatchFn Render dispatch function callback.
RenderListDispatchFn Render dispatch function callback.
ENUMS
FrustumPlanes Frustum planes to use in a frustum
RenderListOperation Render batch callback states
RenderOrder Render order
Result
Visibility Visibility status
STRUCTS
struct FrustumOptions Frustum options used when setting up a draw call
struct RenderListDispatchParams Render dispatch function callback.
struct RenderListVisibilityParams Visibility dispatch function callback.
struct RenderObject Render objects represent an actual draw call
struct StencilTestParams Struct holding stencil operation setup
FUNCTIONS
dmRender::Result AddToRender(dmRender::HRenderContext context, dmRender::RenderObject* ro) Adds a render object to the current render frame
void ClearNamedConstantBuffer(dmRender::HNamedConstantBuffer buffer) Clears a named constant buffer from any constants.
void DeleteConstant(dmRender::HConstant constant) Deletes a shader program constant
void DeleteNamedConstantBuffer(dmRender::HNamedConstantBuffer buffer) Deletes a named constant buffer
dmRenderDDF::MaterialDesc::VertexSpace dmRender::GetMaterialVertexSpace(dmRender::HMaterial material) Get the vertex space (local or world)
void dmRender::RenderObject::MAX_TEXTURE_COUNT() The maximum number of textures the render object c...
int32_t GetConstantLocation(dmRender::HConstant constant) Gets the shader program constant location
dmhash_t GetConstantName(dmRender::HConstant constant) Gets the shader program constant name
void GetConstantName(dmRender::HConstant constant, dmhash_t name) Gets the shader program constant name
dmRenderDDF::MaterialDesc::ConstantType GetConstantType(dmRender::HConstant constant) Gets the type of the constant
dmVMath::Vector4* GetConstantValues(dmRender::HConstant constant, uint32_t* num_values) Gets the shader program constant values
uint32_t GetMaterialTagListKey(dmGraphics::HMaterial material) Gets the key to the material tag list
bool GetNamedConstant(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash, dmVMath::Vector4** values, uint32_t* num_values) Gets a named constant from the buffer
bool GetNamedConstant(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash, dmVMath::Vector4** values, uint32_t* num_values, dmRenderDDF::MaterialDesc::ConstantType* constant_type) Gets a named constant from the buffer - with type ...
bool GetNamedConstantCount(dmRender::HNamedConstantBuffer buffer) Gets number of constants in the buffer
void IterateNamedConstants(dmRender::HNamedConstantBuffer buffer, void (*callback)(dmhash_t name_hash, void* ctx) callback, void* ctx) Iterates over the constants
dmRender::HConstant NewConstant(dmhash_t name_hash) Creates a shader program constant
dmRender::HNamedConstantBuffer NewNamedConstantBuffer() Allocates a named constant buffer
void RemoveNamedConstant(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash) Removes a named constant from the buffer
dmRender::RenderListEntry* RenderListAlloc(dmRender::HRenderContext context, uint32_t entries) Allocates an array of render entries
void RenderListEntry(dmVMath::Point3 m_WorldPosition, uint32_t m_Order, uint32_t m_BatchKey, uint32_t m_TagListKey, uint64_t m_UserData, uint32_t:4 m_MinorOrder, uint32_t:2 m_MajorOrder, uint32_t:8 m_Dispatch) Represents a renderable object (e.g. a single spri...
dmRender::HRenderListDispatch RenderListMakeDispatch(dmRender::HRenderContext context, dmRender::RenderListDispatchFn dispatch_fn, dmRender::RenderListVisibilityFn visibility_fn, void* user_data) Register a render dispatch function
void RenderListSubmit(dmRender::HRenderContext context, dmRender::RenderListEntry* begin, dmRender::RenderListEntry* end) Adds a render object to the current render frame
void SetConstantLocation(dmRender::HConstant constant, dmGraphics::HUniformLocation location) Sets the shader program constant location
void SetConstantType(dmRender::HConstant constant, dmRenderDDF::MaterialDesc::ConstantType type) Sets the type of the constant
dmRender::Result SetConstantValues(dmRender::HConstant constant, dmVMath::Vector4* values, uint32_t num_values) Sets the shader program constant values
void SetNamedConstant(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash, dmVMath::Vector4* values, uint32_t num_values) Sets one or more named constants to the buffer
void SetNamedConstant(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash, dmVMath::Vector4* values, uint32_t num_values, dmRenderDDF::MaterialDesc::ConstantType constant_type) Sets one or more named constants to the buffer wit...
Result SetNamedConstantAtIndex(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash, dmVMath::Vector4 value, uint32_t value_index) Sets a named constant in the buffer at a specific ...
void SetNamedConstants(dmRender::HNamedConstantBuffer buffer, dmRender::HConstant* constants, uint32_t num_constants) Sets a list of named constants to the buffer

Functions

AddToRender

dmRender::Result AddToRender(dmRender::HRenderContext context, dmRender::RenderObject* ro)

Adds a render object to the current render frame

PARAMETERS

dmRender::HRenderContext context the context
dmRender::RenderObject* ro the render object

RETURNS

dmRender::Result the result

ClearNamedConstantBuffer

void ClearNamedConstantBuffer(dmRender::HNamedConstantBuffer buffer)

Clears a named constant buffer from any constants.

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer

DeleteConstant

void DeleteConstant(dmRender::HConstant constant)

Deletes a shader program constant

PARAMETERS

dmRender::HConstant constant The shader constant

DeleteNamedConstantBuffer

void DeleteNamedConstantBuffer(dmRender::HNamedConstantBuffer buffer)

Deletes a named constant buffer

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer

dmRender::GetMaterialVertexSpace

dmRenderDDF::MaterialDesc::VertexSpace dmRender::GetMaterialVertexSpace(dmRender::HMaterial material)

Get the vertex space (local or world)

PARAMETERS

dmRender::HMaterial material the material

RETURNS

dmRenderDDF::MaterialDesc::VertexSpace the vertex space

dmRender::RenderObject::MAX_TEXTURE_COUNT

void dmRender::RenderObject::MAX_TEXTURE_COUNT()

The maximum number of textures the render object can hold (currently 8)

PARAMETERS


GetConstantLocation

int32_t GetConstantLocation(dmRender::HConstant constant)

Gets the shader program constant location

PARAMETERS

dmRender::HConstant constant The shader constant

RETURNS

int32_t the location

GetConstantName

dmhash_t GetConstantName(dmRender::HConstant constant)

Gets the shader program constant name

PARAMETERS

dmRender::HConstant constant The shader constant

RETURNS

dmhash_t the hash name

GetConstantName

void GetConstantName(dmRender::HConstant constant, dmhash_t name)

Gets the shader program constant name

PARAMETERS

dmRender::HConstant constant The shader constant
dmhash_t name the hash name

GetConstantType

dmRenderDDF::MaterialDesc::ConstantType GetConstantType(dmRender::HConstant constant)

Gets the type of the constant

PARAMETERS

dmRender::HConstant constant The shader constant

RETURNS

dmRenderDDF::MaterialDesc::ConstantType the type of the constant

GetConstantValues

dmVMath::Vector4* GetConstantValues(dmRender::HConstant constant, uint32_t* num_values)

Gets the shader program constant values

PARAMETERS

dmRender::HConstant constant The shader constant
uint32_t* num_values (out) the array num_values

RETURNS

dmVMath::Vector4* the uniform values

GetMaterialTagListKey

uint32_t GetMaterialTagListKey(dmGraphics::HMaterial material)

Gets the key to the material tag list

PARAMETERS

dmGraphics::HMaterial material the material

RETURNS

uint32_t the list key

GetNamedConstant

bool GetNamedConstant(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash, dmVMath::Vector4** values, uint32_t* num_values)

Gets a named constant from the buffer

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer
dmhash_t name_hash the name of the constant
dmVMath::Vector4** values (out) the values. May not be null.
uint32_t* num_values (out) the number of values. May not be null.

RETURNS

bool true if constant existed.

GetNamedConstant

bool GetNamedConstant(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash, dmVMath::Vector4** values, uint32_t* num_values, dmRenderDDF::MaterialDesc::ConstantType* constant_type)

Gets a named constant from the buffer - with type information

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer
dmhash_t name_hash the name of the constant
dmVMath::Vector4** values (out) the values. May not be null.
uint32_t* num_values (out) the number of values. May not be null.
dmRenderDDF::MaterialDesc::ConstantType* constant_type (out) the constant type.

RETURNS

bool true if constant existed.

GetNamedConstantCount

bool GetNamedConstantCount(dmRender::HNamedConstantBuffer buffer)

Gets number of constants in the buffer

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer

RETURNS

bool true if constant existed.

IterateNamedConstants

void IterateNamedConstants(dmRender::HNamedConstantBuffer buffer, void (*callback)(dmhash_t name_hash, void* ctx) callback, void* ctx)

Iterates over the constants

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer
void (*callback)(dmhash_t name_hash, void* ctx) callback the callback function void (callback)(dmhash_t name_hash, void ctx)
void* ctx the callback context

NewConstant

dmRender::HConstant NewConstant(dmhash_t name_hash)

Creates a shader program constant

PARAMETERS

dmhash_t name_hash the name of the material constant

RETURNS

dmRender::HConstant the constant

NewNamedConstantBuffer

dmRender::HNamedConstantBuffer NewNamedConstantBuffer()

Allocates a named constant buffer

PARAMETERS

RETURNS

dmRender::HNamedConstantBuffer the constants buffer

RemoveNamedConstant

void RemoveNamedConstant(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash)

Removes a named constant from the buffer

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer
dmhash_t name_hash the name of the constant

RenderListAlloc

dmRender::RenderListEntry* RenderListAlloc(dmRender::HRenderContext context, uint32_t entries)

Allocates an array of render entries

PARAMETERS

dmRender::HRenderContext context the context
uint32_t entries the number of entries to allocate

RETURNS

dmRender::RenderListEntry* the render list entry array

RenderListEntry

void RenderListEntry(dmVMath::Point3 m_WorldPosition, uint32_t m_Order, uint32_t m_BatchKey, uint32_t m_TagListKey, uint64_t m_UserData, uint32_t:4 m_MinorOrder, uint32_t:2 m_MajorOrder, uint32_t:8 m_Dispatch)

Represents a renderable object (e.g. a single sprite) The renderer will (each frame) collect all entries with the current material tag, then batch these objects together. Batching is done based on the batch key and Z value (or order for GUI nodes) The caller will also register a callback function where the batched entries will be returned. Each callback then represents a draw call, and will register a RenderObject

PARAMETERS

dmVMath::Point3 m_WorldPosition the world position of the object
uint32_t m_Order the order to sort on (used if m_MajorOrder != RENDER_ORDER_WORLD)
uint32_t m_BatchKey the batch key to sort on (note: only 48 bits are currently used by renderer)
uint32_t m_TagListKey the key to the list of material tags
uint64_t m_UserData user data (available in the render dispatch callback)
uint32_t:4 m_MinorOrder used to sort within a batch
uint32_t:2 m_MajorOrder If RENDER_ORDER_WORLD, then sorting is done based on the world position. Otherwise the sorting uses the m_Order value directly.
uint32_t:8 m_Dispatch The dispatch function callback (dmRender::HRenderListDispatch)

RenderListMakeDispatch

dmRender::HRenderListDispatch RenderListMakeDispatch(dmRender::HRenderContext context, dmRender::RenderListDispatchFn dispatch_fn, dmRender::RenderListVisibilityFn visibility_fn, void* user_data)

Register a render dispatch function

PARAMETERS

dmRender::HRenderContext context the context
dmRender::RenderListDispatchFn dispatch_fn the render batch callback function
dmRender::RenderListVisibilityFn visibility_fn the render list visibility callback function. May be 0
void* user_data userdata to the callback

RETURNS

dmRender::HRenderListDispatch the render dispatch function handle

RenderListSubmit

void RenderListSubmit(dmRender::HRenderContext context, dmRender::RenderListEntry* begin, dmRender::RenderListEntry* end)

Adds a render object to the current render frame

PARAMETERS

dmRender::HRenderContext context the context
dmRender::RenderListEntry* begin the start of the array
dmRender::RenderListEntry* end the end of the array (i.e. "while begin!=end: *begin ..."")

SetConstantLocation

void SetConstantLocation(dmRender::HConstant constant, dmGraphics::HUniformLocation location)

Sets the shader program constant location

PARAMETERS

dmRender::HConstant constant The shader constant
dmGraphics::HUniformLocation location the location

SetConstantType

void SetConstantType(dmRender::HConstant constant, dmRenderDDF::MaterialDesc::ConstantType type)

Sets the type of the constant

PARAMETERS

dmRender::HConstant constant The shader constant
dmRenderDDF::MaterialDesc::ConstantType type the type of the constant

SetConstantValues

dmRender::Result SetConstantValues(dmRender::HConstant constant, dmVMath::Vector4* values, uint32_t num_values)

Sets the shader program constant values

PARAMETERS

dmRender::HConstant constant The shader constant
dmVMath::Vector4* values the array values
uint32_t num_values the array size (number of Vector4's)

RETURNS

dmRender::Result the result

SetNamedConstant

void SetNamedConstant(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash, dmVMath::Vector4* values, uint32_t num_values)

Sets one or more named constants to the buffer

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer
dmhash_t name_hash the name of the constant
dmVMath::Vector4* values the values
uint32_t num_values the number of values

SetNamedConstant

void SetNamedConstant(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash, dmVMath::Vector4* values, uint32_t num_values, dmRenderDDF::MaterialDesc::ConstantType constant_type)

Sets one or more named constants to the buffer with a specified data type. Currently only dmRenderDDF::MaterialDesc::CONSTANT_TYPE_USER and dmRenderDDF::MaterialDesc::CONSTANT_TYPE_USER_MATRIX4 are supported.

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer
dmhash_t name_hash the name of the constant
dmVMath::Vector4* values the values
uint32_t num_values the number of values
dmRenderDDF::MaterialDesc::ConstantType constant_type The constant type

SetNamedConstantAtIndex

Result SetNamedConstantAtIndex(dmRender::HNamedConstantBuffer buffer, dmhash_t name_hash, dmVMath::Vector4 value, uint32_t value_index)

Sets a named constant in the buffer at a specific index

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer
dmhash_t name_hash the name of the constant
dmVMath::Vector4 value the value
uint32_t value_index the index of the value to set

RETURNS

Result the result

SetNamedConstants

void SetNamedConstants(dmRender::HNamedConstantBuffer buffer, dmRender::HConstant* constants, uint32_t num_constants)

Sets a list of named constants to the buffer

PARAMETERS

dmRender::HNamedConstantBuffer buffer the constants buffer
dmRender::HConstant* constants the constants
uint32_t num_constants the number of constants

Structs

FrustumOptions

TYPE

struct FrustumOptions

Frustum options used when setting up a draw call

MEMBERS

matrix4 m_FrustumMatrix the frustum matrix
bool m_SkipNearFarPlanes should the frustum culling use the near and far planes


RenderListDispatchParams

TYPE

struct RenderListDispatchParams

Render dispatch function callback.

MEMBERS

dmRender::HRenderContext m_Context the context
void* m_UserData the callback user data (registered with RenderListMakeDispatch())
dmRender::RenderListOperation m_Operation the operation
dmRender::RenderListEntry m_Buf the render entry array
uint32_t* m_Begin the start of the render batch. contains index into the m_Buf array
uint32_t* m_End the end of the render batch. Loop while "m_Begin != m_End"


RenderListVisibilityParams

TYPE

struct RenderListVisibilityParams

Visibility dispatch function callback.

MEMBERS

void* m_UserData the callback user data (registered with RenderListMakeDispatch())
dmRender::RenderListEntry m_Entries the render entry array
uint32_t m_NumEntries the number of render entries in the array


RenderObject

TYPE

struct RenderObject

Render objects represent an actual draw call

MEMBERS

dmRender::HConstant[ m_Constants ] the shader constants
dmVMath::Matrix4 m_WorldTransform the world transform (usually identity for batched objects)
dmVMath::Matrix4 m_TextureTransform the texture transform
dmGraphics::HVertexBuffer m_VertexBuffer the vertex buffer
dmGraphics::HVertexDeclaration m_VertexDeclaration the vertex declaration
dmGraphics::HIndexBuffer m_IndexBuffer the index buffer
dmRender::HMaterial m_Material the material
dmGraphics::HTexture[ m_Textures ] the textures
dmGraphics::PrimitiveType m_PrimitiveType the primitive type
dmGraphics::Type m_IndexType the index type (16/32 bit)
dmGraphics::BlendFactor m_SourceBlendFactor the source blend factor
dmGraphics::BlendFactor m_DestinationBlendFactor the destination blend factor
dmRender::StencilTestParams m_StencilTestParams the stencil test params
uint32_t m_VertexStart the vertex start
uint32_t m_VertexCount the vertex count
uint8_t:1 m_SetBlendFactors use the blend factors
uint8_t:1 m_SetStencilTest use the stencil test


StencilTestParams

TYPE

struct StencilTestParams

Struct holding stencil operation setup

MEMBERS

dmGraphics::CompareFunc m_Func the compare function
dmGraphics::StencilOp m_OpSFail the stencil fail operation
dmGraphics::StencilOp m_OpDPFail the depth pass fail operation
dmGraphics::StencilOp m_OpDPPass the depth pass pass operation
uint8_t m_Ref
uint8_t m_RefMask
uint8_t m_BufferMask
uint8_t:4 m_ColorBufferMask
uint8_t:1 m_ClearBuffer


Types

HConstant

Shader constant handle


HFont

Font map handle


HMaterial

Material instance handle


HNamedConstantBuffer

Shader constant buffer handle. Holds name and values for a constant.


HRenderContext

The render context


HRenderListDispatch

Render dispatch function handle.


RenderListDispatchFn

Render dispatch function callback.


RenderListDispatchFn

Render dispatch function callback.


Enums

FrustumPlanes

Frustum planes to use in a frustum

FRUSTUM_PLANES_SIDES
FRUSTUM_PLANES_ALL

RenderListOperation

Render batch callback states

RENDER_LIST_OPERATION_BEGIN
RENDER_LIST_OPERATION_BATCH
RENDER_LIST_OPERATION_END

RenderOrder

Render order

RENDER_ORDER_WORLD
      Used by game objects
RENDER_ORDER_AFTER_WORLD
Used by gui

Result

RESULT_OK
RESULT_INVALID_CONTEXT
RESULT_OUT_OF_RESOURCES
RESULT_BUFFER_IS_FULL
RESULT_INVALID_PARAMETER

Visibility

Visibility status

VISIBILITY_NONE
VISIBILITY_FULL