Namespace: dmRender
Language: C++
Type: Defold C++
File: render.h
Source: engine/render/src/dmsdk/render/render.h
Include: dmsdk/render/render.h
Api for render specific data
Type: FUNCTION Adds a render object to the current render frame
Parameters
context (dmRender::HRenderContext) - the contextro (dmRender::RenderObject*) - the render objectReturns
result (dmRender::Result) - the resultType: FUNCTION
Parameters
render_context (dmRender::HRenderContext) - Render contextmaterial (dmRender::Material)render_object (const dmRender::RenderObject*)Type: FUNCTION
Parameters
render_context (dmRender::HRenderContext)material (dmRender::HMaterial)sampler (dmRender::HSampler)value_index (uint8_t)texture (dmGraphics::HTexture)Type: FUNCTION
Parameters
material (dmRender::HMaterial)Type: FUNCTION Clears a named constant buffer from any constants.
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants bufferType: FUNCTION Deletes a shader program constant
Parameters
constant (dmRender::HConstant) - The shader constantType: FUNCTION
Parameters
render_context (dmRender::HRenderContext) - Render contextmaterial (dmRender::Material)Type: FUNCTION Deletes a named constant buffer
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants bufferType: FUNCTION Disables the item, invalidates its handle and releases its slot for reuse. Call before subsequent draws and outside dispatch callbacks. User data is not released.
Parameters
context (dmRender::HRenderContext) - the render contextitem (dmRender::HRenderItem) - an item created in this contextReturns
result (bool) - true on success, or false if the item handle is invalid or deletedType: FUNCTION Get the vertex space (local or world)
Parameters
material (dmRender::HMaterial) - the materialReturns
vertex_space (dmRenderDDF::MaterialDesc::VertexSpace) - the vertex spaceType: CONSTANT The maximum number of textures the render object can hold (16)
Type: FUNCTION Changes draw eligibility without releasing the handle or its data. Repeating the current enabled state has no effect. The dispatch must also be submitted for the item to participate in the current frame.
Parameters
context (dmRender::HRenderContext) - the render contextitem (dmRender::HRenderItem) - an item created in this contextenabled (bool) - true to enable the item, or false to disable itReturns
result (bool) - true on success, or false if the item handle is invalid or deletedType: STRUCT Frustum options used when setting up a draw call
Members
m_FrustumMatrix (matrix4) - the frustum matrixm_SkipNearFarPlanes (bool) - should the frustum culling use the near and far planesType: ENUM Frustum planes to use in a frustum
Members
FRUSTUM_PLANES_SIDESFRUSTUM_PLANES_ALLType: FUNCTION Gets the shader program constant location
Parameters
constant (dmRender::HConstant) - The shader constantReturns
location (int32_t) - the locationType: FUNCTION Gets the shader program constant name
Parameters
constant (dmRender::HConstant) - The shader constantReturns
name (dmhash_t) - the hash nameType: FUNCTION Gets the shader program constant name
Parameters
constant (dmRender::HConstant) - The shader constantname (dmhash_t) - the hash nameType: FUNCTION Gets the type of the constant
Parameters
constant (dmRender::HConstant) - The shader constantReturns
type (dmRenderDDF::MaterialDesc::ConstantType) - the type of the constantType: FUNCTION Gets the shader program constant values
Parameters
constant (dmRender::HConstant) - The shader constantnum_values (uint32_t*) - (out) the array num_valuesReturns
values (dmVMath::Vector4*) - the uniform valuesType: FUNCTION
Type: FUNCTION
Parameters
material (dmRender::HMaterial)unit (uint32_t)Returns
name_hash (dmhash_t)Type: FUNCTION
Parameters
material (dmRender::HMaterial)name_hash (dmhash_t)Returns
sampler_unit (uint32_t)Type: FUNCTION Gets the key to the material tag list
Parameters
material (dmGraphics::HMaterial) - the materialReturns
listkey (uint32_t) - the list keyType: FUNCTION Gets a named constant from the buffer
Notes
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants buffername_hash (dmhash_t) - the name of the constantvalues (dmVMath::Vector4**) - (out) the values. May not be null.num_values (uint32_t*) - (out) the number of values. May not be null.Returns
ok (bool) - true if constant existed.Type: FUNCTION Gets a named constant from the buffer - with type information
Notes
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants buffername_hash (dmhash_t) - the name of the constantvalues (dmVMath::Vector4**) - (out) the values. May not be null.num_values (uint32_t*) - (out) the number of values. May not be null.constant_type (dmRenderDDF::MaterialDesc::ConstantType*) - (out) the constant type.Returns
ok (bool) - true if constant existed.Type: FUNCTION Gets number of constants in the buffer
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants bufferReturns
ok (bool) - true if constant existed.Type: FUNCTION
Parameters
render_context (dmRender::HRenderContext) - Render contextReturns
view_matrix (const dmVMath::Matrix4&)Type: TYPEDEF Shader constant handle
Type: TYPEDEF Font map handle
Type: TYPEDEF Light prototype handle. Used to create light instances.
Type: TYPEDEF Material instance handle
Type: TYPEDEF Shader constant buffer handle. Holds name and values for a constant.
Type: TYPEDEF The render context
Type: TYPEDEF Identifies a renderer-owned item until DeleteRenderItem() invalidates it. Zero is invalid. Use the handle only with the context that created it. Create and update items before the draw that consumes them, outside render dispatch callbacks. Item setters return false for invalid or deleted handles.
Type: TYPEDEF Identifies a registration created by RegisterRenderListDispatch(). Use it only with its creating context, and never after UnregisterRenderListDispatch(). This handle is separate from the frame-local HRenderListDispatch used in RenderListEntry. Zero is invalid.
Type: TYPEDEF Render dispatch function handle.
Type: TYPEDEF Sampler handle
Type: FUNCTION Iterates over the constants
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants buffercallback (IterateNamedConstantsFn) - the callback functionctx (void*) - the callback contextType: TYPEDEF
Parameters
name_hash (dmhash_t)ctx (void*)Type: FUNCTION Creates a shader program constant
Parameters
name_hash (dmhash_t) - the name of the material constantReturns
constant (dmRender::HConstant) - the constantType: FUNCTION
Parameters
render_context (dmRender::HContext) - Render contextprogram (dmGraphics::HProgram)Returns
new_material (dmRender::HMaterial)Type: FUNCTION Allocates a named constant buffer
Returns
buffer (dmRender::HNamedConstantBuffer) - the constants bufferType: FUNCTION The new item is disabled, with an identity transform, no material tags or bounds, and world-position ordering. Its dispatch and user data are fixed for its lifetime. Any data referenced by user_data must outlive the item. Creating an item does not invalidate outstanding RenderListAlloc() ranges. Delete the item before unregistering its dispatch.
Parameters
context (dmRender::HRenderContext) - the render contextdispatch (dmRender::HRenderItemDispatch) - a registration created in this contextuser_data (uint64_t) - item data exposed as RenderListEntry::m_UserData in callbacksReturns
item (dmRender::HRenderItem) - the item handleExamples
#include
// context, dispatch and material are owned by the component or its world.
dmRender::HRenderItem item = dmRender::NewRenderItem(context, dispatch, user_data);
dmRender::SetMaterial(context, item, material);
dmRender::SetWorldTransform(context, item, world_transform);
dmRender::SetBoundingOBB(context, item, local_min, local_max);
dmRender::Enable(context, item, true);
// In the component render callback each frame:
dmRender::SubmitRenderListDispatch(context, dispatch);
// When the component is destroyed, outside dispatch callbacks:
dmRender::DeleteRenderItem(context, item);
Type: FUNCTION Callbacks and user data remain caller-owned and must stay valid until unregistration. Register before submitting. Delete all associated items before unregistering, after the current render list has finished drawing.
Parameters
context (dmRender::HRenderContext) - the render contextdispatch_fn (dmRender::RenderListDispatchFn) - the render batch callbackvisibility_fn (dmRender::RenderListVisibilityFn) - visibility callback for items without typed bounds, or 0 for always visibleuser_data (void*) - user data passed to both callbacksReturns
dispatch (dmRender::HRenderItemDispatch) - the registration, or 0 if the registration limit is reachedType: FUNCTION Removes a named constant from the buffer
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants buffername_hash (dmhash_t) - the name of the constantType: CONSTANT Name used when registering the render context with the engine context registry.
Type: FUNCTION Allocate frame-local render entries Deprecated: use NewRenderItem() and the render item setters. Emits a warning once per process. Do not retain pointers across frames; another allocation can also invalidate the returned range.
Parameters
context (dmRender::HRenderContext) - the contextentries (uint32_t) - the number of entries to allocateReturns
array (dmRender::RenderListEntry*) - the render list entry arrayType: TYPEDEF Render dispatch function callback.
Parameters
params (dmRender::RenderListDispatchParams) - the paramsType: STRUCT Render dispatch function callback.
Members
m_Context (dmRender::HRenderContext) - the contextm_UserData (void*) - the callback user data supplied to RegisterRenderListDispatch() or RenderListMakeDispatch()m_Operation (dmRender::RenderListOperation) - the operationm_Buf (dmRender::RenderListEntry) - the render entry arraym_Begin (uint32_t*) - the start of the render batch. contains index into the m_Buf arraym_End (uint32_t*) - the end of the render batch. Loop while “m_Begin != m_End”Type: FUNCTION 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
m_WorldPosition (dmVMath::Point3) - the world position of the objectm_UserData (uint64_t) - user data (available in the render dispatch callback)m_Order (uint32_t) - the order to sort on (used if m_MajorOrder != RENDER_ORDER_WORLD)m_BatchKey (uint32_t) - the batch key to sort on (note: only 48 bits are currently used by renderer)m_TagListKey (uint32_t) - the key to the list of material tagsm_FrustumHash (uint32_t) - Last combined frustum cull key (note: engine internal use only!)m_MinorOrder (uint32_t:4) - used to sort within a batchm_MajorOrder (uint32_t:2) - If RENDER_ORDER_WORLD, then sorting is done based on the world position.
Otherwise the sorting uses the m_Order value directly.m_Dispatch (uint32_t:8) - The dispatch function callback (dmRender::HRenderListDispatch)m_Visibility (uint32_t:1) - Visibility flag. Used for frustrum culling. See enum VisibilityType: FUNCTION Register a frame-local render dispatch function Deprecated: use RegisterRenderListDispatch() and SubmitRenderListDispatch(). Emits a warning once per process. The overload without a visibility callback is also deprecated.
Parameters
context (dmRender::HRenderContext) - the contextdispatch_fn (dmRender::RenderListDispatchFn) - the render batch callback functionvisibility_fn (dmRender::RenderListVisibilityFn) - the render list visibility callback function. May be 0user_data (void*) - userdata to the callbackReturns
dispatch (dmRender::HRenderListDispatch) - the render dispatch function handleType: ENUM Render batch callback states
Members
RENDER_LIST_OPERATION_BEGINRENDER_LIST_OPERATION_BATCHRENDER_LIST_OPERATION_ENDType: FUNCTION Submit frame-local render entries Deprecated: use Enable() and SubmitRenderListDispatch(). Emits a warning once per process. The range must come from a single RenderListAlloc() call.
Parameters
context (dmRender::HRenderContext) - the contextbegin (dmRender::RenderListEntry*) - the start of the arrayend (dmRender::RenderListEntry*) - the end of the array (i.e. “while begin!=end: *begin …””)Type: TYPEDEF Render visibility function callback.
Parameters
params (dmRender::RenderListVisibilityParams) - the paramsType: STRUCT Visibility dispatch function callback.
Members
m_UserData (void*) - the callback user data supplied to RegisterRenderListDispatch() or RenderListMakeDispatch()m_Entries (dmRender::RenderListEntry) - the render entry arraym_NumEntries (uint32_t) - the number of render entries in the arrayType: STRUCT Render objects represent an actual draw call
Members
m_Constants (dmRender::HConstant[]) - the shader constantsm_WorldTransform (dmVMath::Matrix4) - the world transform (usually identity for batched objects)m_TextureTransform (dmVMath::Matrix4) - the texture transformm_VertexBuffer (dmGraphics::HVertexBuffer) - the vertex bufferm_VertexDeclaration (dmGraphics::HVertexDeclaration) - the vertex declarationm_IndexBuffer (dmGraphics::HIndexBuffer) - the index bufferm_Material (dmRender::HMaterial) - the materialm_Textures (dmGraphics::HTexture[]) - the texturesm_PrimitiveType (dmGraphics::PrimitiveType) - the primitive typem_IndexType (dmGraphics::Type) - the index type (16/32 bit)m_SourceBlendFactor (dmGraphics::BlendFactor) - the source blend factorm_DestinationBlendFactor (dmGraphics::BlendFactor) - the destination blend factorm_StencilTestParams (dmRender::StencilTestParams) - the stencil test paramsm_VertexStart (uint32_t) - the vertex startm_VertexCount (uint32_t) - the vertex countm_SetBlendFactors (uint8_t:1) - use the blend factorsm_SetStencilTest (uint8_t:1) - use the stencil testType: ENUM Render order
Members
RENDER_ORDER_BEFORE_WORLD - Drawn before world-sorted itemsRENDER_ORDER_WORLD - <div class="codehilite"><pre> Used by game objects
</pre></div>RENDER_ORDER_AFTER_WORLD - <div class="codehilite"><pre>Used by gui
</pre></div>Type: ENUM
Members
RESULT_OKRESULT_INVALID_CONTEXTRESULT_OUT_OF_RESOURCESRESULT_BUFFER_IS_FULLRESULT_INVALID_PARAMETERType: FUNCTION Sets the caller’s batch compatibility key. Equal keys allow batching only when the remaining state is compatible. The renderer also separates batches by dispatch and ordering.
Parameters
context (dmRender::HRenderContext) - the render contextitem (dmRender::HRenderItem) - an item created in this contextkey (uint32_t) - the batch compatibility keyReturns
result (bool) - true on success, or false if the item handle is invalid or deletedType: FUNCTION Replaces the previous volume. If any minimum coordinate exceeds its maximum, removes typed bounds and restores the registration’s visibility callback, or always-visible behavior when no callback is registered. Equal corners define a valid point. SetWorldTransform() does not transform this box. Visibility is invalidated only when the volume type or values change.
Parameters
context (dmRender::HRenderContext) - the render contextitem (dmRender::HRenderItem) - an item created in this contextworld_min (dmVMath::Vector3) - the world-space minimum cornerworld_max (dmVMath::Vector3) - the world-space maximum cornerReturns
result (bool) - true on success, or false if the item handle is invalid or deletedType: FUNCTION Replaces the previous volume. Each minimum coordinate must be no greater than its maximum coordinate. The item’s world transform supplies position, orientation and scale, including reflection and shear. Visibility is invalidated only when the volume type or values change.
Parameters
context (dmRender::HRenderContext) - the render contextitem (dmRender::HRenderItem) - an item created in this contextlocal_min (dmVMath::Vector3) - the local-space minimum cornerlocal_max (dmVMath::Vector3) - the local-space maximum cornerReturns
result (bool) - true on success, or false if the item handle is invalid or deletedType: FUNCTION Replaces the previous volume. The radius is a non-negative distance, not a squared radius. SetWorldTransform() does not move or scale this sphere. Visibility is invalidated only when the volume type or values change.
Parameters
context (dmRender::HRenderContext) - the render contextitem (dmRender::HRenderItem) - an item created in this contextworld_center (dmVMath::Point3) - the world-space sphere centerradius (float) - the non-negative sphere radius in world unitsReturns
result (bool) - true on success, or false if the item handle is invalid or deletedType: FUNCTION Sets the shader program constant location
Parameters
constant (dmRender::HConstant) - The shader constantlocation (dmGraphics::HUniformLocation) - the locationType: FUNCTION Sets the type of the constant
Parameters
constant (dmRender::HConstant) - The shader constanttype (dmRenderDDF::MaterialDesc::ConstantType) - the type of the constantType: FUNCTION Sets the shader program constant values
Parameters
constant (dmRender::HConstant) - The shader constantvalues (dmVMath::Vector4*) - the array valuesnum_values (uint32_t) - the array size (number of Vector4’s)Returns
result (dmRender::Result) - the resultType: FUNCTION Copies the material’s predicate tags. Call again after changing material tags to refresh cached metadata. A null material clears the tags. The material is not retained. Ordering is unchanged; use SetOrder() to configure it.
Parameters
context (dmRender::HRenderContext) - the render contextitem (dmRender::HRenderItem) - an item created in this contextmaterial (dmRender::HMaterial) - the material supplying predicate tags, or 0 to clear themReturns
result (bool) - true on success, or false if the item handle is invalid or deletedType: FUNCTION
Parameters
material (dmRender::HMaterial)name_hash (dmhash_t)unit (uint32_t)u_wrap (dmGraphics::TextureWrap)v_wrap (dmGraphics::TextureWrap)w_wrap (dmGraphics::TextureWrap)min_filter (dmGraphics::TextureFilter)mag_filter (dmGraphics::TextureFilter)max_anisotropy (float)Returns
is_succeed (bool)Type: FUNCTION
Parameters
material (dmRender::HMaterial)name_hash (dmhash_t)unit (uint32_t)u_wrap (dmGraphics::TextureWrap)v_wrap (dmGraphics::TextureWrap)min_filter (dmGraphics::TextureFilter)mag_filter (dmGraphics::TextureFilter)max_anisotropy (float)Returns
is_succeed (bool)Type: FUNCTION
Parameters
material (dmRender::Material)tag_count (uint32_t)tags (const dmhash_t*)Type: FUNCTION Sets one or more named constants to the buffer
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants buffername_hash (dmhash_t) - the name of the constantvalues (dmVMath::Vector4*) - the valuesnum_values (uint32_t) - the number of valuesType: FUNCTION Sets one or more named constants to the buffer with a specified data type. Currently only dmRenderDDF::MaterialDesc::CONSTANT_TYPE_USER, dmRenderDDF::MaterialDesc::CONSTANT_TYPE_USER_COLOR and dmRenderDDF::MaterialDesc::CONSTANT_TYPE_USER_MATRIX4 are supported.
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants buffername_hash (dmhash_t) - the name of the constantvalues (dmVMath::Vector4*) - the valuesnum_values (uint32_t) - the number of valuesconstant_type (dmRenderDDF::MaterialDesc::ConstantType) - The constant typeType: FUNCTION Sets a named constant in the buffer at a specific index
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants buffername_hash (dmhash_t) - the name of the constantvalue (dmVMath::Vector4) - the valuevalue_index (uint32_t) - the index of the value to setReturns
result (Result) - the resultType: FUNCTION Sets a list of named constants to the buffer
Parameters
buffer (dmRender::HNamedConstantBuffer) - the constants bufferconstants (dmRender::HConstant*) - the constantsnum_constants (uint32_t) - the number of constantsType: FUNCTION Overrides the default world-position ordering. World order sorts by position. Before-world and after-world order use the supplied order value; only its low 24 bits are retained. Material changes and render-script material overrides preserve this ordering.
Parameters
context (dmRender::HRenderContext) - the render contextitem (dmRender::HRenderItem) - an item created in this contextrender_order (dmRender::RenderOrder) - the major rendering orderorder (uint32_t) - the 24-bit order value, ignored for world-position sortingReturns
result (bool) - true on success, or false if the item handle is invalid or deletedType: FUNCTION Copies the local-to-world affine transform. Its translation supplies the sort position, and it transforms local OBB bounds. World-space sphere and AABB bounds are unaffected. Every call invalidates cached visibility; also call when callback-owned visibility data changes without a transform change.
Parameters
context (dmRender::HRenderContext) - the render contextitem (dmRender::HRenderItem) - an item created in this contextworld_transform (dmVMath::Matrix4) - the affine local-to-world transform to copyReturns
result (bool) - true on success, or false if the item handle is invalid or deletedType: STRUCT Struct holding stencil operation setup
Members
m_Func (dmGraphics::CompareFunc) - the compare functionm_OpSFail (dmGraphics::StencilOp) - the stencil fail operationm_OpDPFail (dmGraphics::StencilOp) - the depth pass fail operationm_OpDPPass (dmGraphics::StencilOp) - the depth pass pass operationm_Ref (uint8_t)m_RefMask (uint8_t)m_BufferMask (uint8_t)m_ColorBufferMask (uint8_t:4)m_ClearBuffer (uint8_t:1)Type: FUNCTION Makes the registration’s enabled items eligible for this frame. Call between RenderListBegin() and RenderListEnd(), before render-script draws. Repeated submission in one frame has no effect. Only submitted registrations consume frame dispatch IDs; at most 255 are available, shared with legacy dispatches. If that limit is reached, an error is logged and this submission is skipped.
Parameters
context (dmRender::HRenderContext) - the render contextdispatch (dmRender::HRenderItemDispatch) - a registration created in this contextType: FUNCTION Delete all items belonging to this registration first. Call only after all draws using the current render list have finished, before the next render list is submitted. The registration handle becomes invalid. This does not release caller-owned callbacks or user data.
Parameters
context (dmRender::HRenderContext) - the render contextdispatch (dmRender::HRenderItemDispatch) - a registration created in this contextType: ENUM Visibility status
Members
VISIBILITY_NONEVISIBILITY_FULL