API reference (Render)

Defold c++

Defold lua

Extension

Version

Render

Api for render specific data


Namespace:	`dmRender`
Include:	`#include <dmsdk/render/render.h>`

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.
IterateNamedConstantsFn
RenderListDispatchFn	Render dispatch function callback.
RenderListVisibilityFn	Render visibility function callback.

CONSTANTS
dmRender::RenderObject::MAX_TEXTURE_COUNT	The maximum number of textures the render object c...

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 ApplyMaterialConstants(dmRender::HRenderContext render_context, dmRender::Material material, const dmRender::RenderObject* render_object)
void ApplyMaterialSampler(dmRender::HRenderContext render_context, dmRender::HMaterial material, dmRender::HSampler sampler, uint8_t value_index, dmGraphics::HTexture texture)
void ClearMaterialTags(dmRender::HMaterial material)
void ClearNamedConstantBuffer(dmRender::HNamedConstantBuffer buffer)	Clears a named constant buffer from any constants.
void DeleteConstant(dmRender::HConstant constant)	Deletes a shader program constant
void DeleteMaterial(dmRender::HRenderContext render_context, dmRender::Material material)
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)
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
void GetMaterialSampler()
dmhash_t GetMaterialSamplerNameHash(dmRender::HMaterial material, uint32_t unit)
uint32_t GetMaterialSamplerUnit(dmRender::HMaterial material, dmhash_t name_hash)
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
const dmVMath::Matrix4& GetViewMatrix(dmRender::HRenderContext render_context)
void IterateNamedConstants(dmRender::HNamedConstantBuffer buffer, IterateNamedConstantsFn callback, void* ctx)	Iterates over the constants
dmRender::HConstant NewConstant(dmhash_t name_hash)	Creates a shader program constant
dmRender::HMaterial NewMaterial(dmRender::HContext render_context, dmGraphics::HProgram program)
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, uint32_t:1 m_Visibility)	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
bool SetMaterialSampler(dmRender::HMaterial material, dmhash_t name_hash, uint32_t unit, dmGraphics::TextureWrap u_wrap, dmGraphics::TextureWrap v_wrap, dmGraphics::TextureFilter min_filter, dmGraphics::TextureFilter mag_filter, float max_anisotropy)
void SetMaterialTags(dmRender::Material material, uint32_t tag_count, const dmhash_t* tags)
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

ApplyMaterialConstants

void ApplyMaterialConstants(dmRender::HRenderContext render_context, dmRender::Material material, const dmRender::RenderObject* render_object)

PARAMETERS

`dmRender::HRenderContext`	`render_context`	Render context
`dmRender::Material`	`material`
`const dmRender::RenderObject*`	`render_object`

ApplyMaterialSampler

void ApplyMaterialSampler(dmRender::HRenderContext render_context, dmRender::HMaterial material, dmRender::HSampler sampler, uint8_t value_index, dmGraphics::HTexture texture)

PARAMETERS

`dmRender::HRenderContext`	`render_context`
`dmRender::HMaterial`	`material`
`dmRender::HSampler`	`sampler`
`uint8_t`	`value_index`
`dmGraphics::HTexture`	`texture`

ClearMaterialTags

void ClearMaterialTags(dmRender::HMaterial material)

PARAMETERS

dmRender::HMaterial material

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

DeleteMaterial

void DeleteMaterial(dmRender::HRenderContext render_context, dmRender::Material material)

PARAMETERS

`dmRender::HRenderContext`	`render_context`	Render context
`dmRender::Material`	`material`

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

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

GetMaterialSampler

void GetMaterialSampler()

PARAMETERS

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.

GetViewMatrix

const dmVMath::Matrix4& GetViewMatrix(dmRender::HRenderContext render_context)

PARAMETERS

dmRender::HRenderContext render_context Render context

RETURNS

const dmVMath::Matrix4&

IterateNamedConstants

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

Iterates over the constants

PARAMETERS

`dmRender::HNamedConstantBuffer`	`buffer`	the constants buffer
`IterateNamedConstantsFn`	`callback`	the callback function
`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

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, uint32_t:1 m_Visibility)

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)
`uint32_t:1`	`m_Visibility`	Visibility flag. Used for frustrum culling. See enum Visibility

RenderListMakeDispatch

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

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

SetMaterialSampler

bool SetMaterialSampler(dmRender::HMaterial material, dmhash_t name_hash, uint32_t unit, dmGraphics::TextureWrap u_wrap, dmGraphics::TextureWrap v_wrap, dmGraphics::TextureFilter min_filter, dmGraphics::TextureFilter mag_filter, float max_anisotropy)

PARAMETERS

`dmRender::HMaterial`	`material`
`dmhash_t`	`name_hash`
`uint32_t`	`unit`
`dmGraphics::TextureWrap`	`u_wrap`
`dmGraphics::TextureWrap`	`v_wrap`
`dmGraphics::TextureFilter`	`min_filter`
`dmGraphics::TextureFilter`	`mag_filter`
`float`	`max_anisotropy`

RETURNS

bool

SetMaterialTags

void SetMaterialTags(dmRender::Material material, uint32_t tag_count, const dmhash_t* tags)

PARAMETERS

`dmRender::Material`	`material`
`uint32_t`	`tag_count`
`const dmhash_t*`	`tags`

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`