Render

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

API

AddToRender

Type: FUNCTION Adds a render object to the current render frame

Parameters

Returns

ApplyMaterialConstants

Type: FUNCTION

Parameters

ApplyMaterialSampler

Type: FUNCTION

Parameters

ClearMaterialTags

Type: FUNCTION

Parameters

ClearNamedConstantBuffer

Type: FUNCTION Clears a named constant buffer from any constants.

Parameters

DeleteConstant

Type: FUNCTION Deletes a shader program constant

Parameters

DeleteMaterial

Type: FUNCTION

Parameters

DeleteNamedConstantBuffer

Type: FUNCTION Deletes a named constant buffer

Parameters

DeleteRenderItem

Type: 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

Returns

dmRender::GetMaterialVertexSpace

Type: FUNCTION Get the vertex space (local or world)

Parameters

Returns

dmRender::RenderObject::MAX_TEXTURE_COUNT

Type: CONSTANT The maximum number of textures the render object can hold (16)

Enable

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

Returns

FrustumOptions

Type: STRUCT Frustum options used when setting up a draw call

Members

FrustumPlanes

Type: ENUM Frustum planes to use in a frustum

Members

GetConstantLocation

Type: FUNCTION Gets the shader program constant location

Parameters

Returns

GetConstantName

Type: FUNCTION Gets the shader program constant name

Parameters

Returns

GetConstantName

Type: FUNCTION Gets the shader program constant name

Parameters

GetConstantType

Type: FUNCTION Gets the type of the constant

Parameters

Returns

GetConstantValues

Type: FUNCTION Gets the shader program constant values

Parameters

Returns

GetMaterialSampler

Type: FUNCTION

GetMaterialSamplerNameHash

Type: FUNCTION

Parameters

Returns

GetMaterialSamplerUnit

Type: FUNCTION

Parameters

Returns

GetMaterialTagListKey

Type: FUNCTION Gets the key to the material tag list

Parameters

Returns

GetNamedConstant

Type: FUNCTION Gets a named constant from the buffer

Notes

Parameters

Returns

GetNamedConstant

Type: FUNCTION Gets a named constant from the buffer - with type information

Notes

Parameters

Returns

GetNamedConstantCount

Type: FUNCTION Gets number of constants in the buffer

Parameters

Returns

GetViewMatrix

Type: FUNCTION

Parameters

Returns

HConstant

Type: TYPEDEF Shader constant handle

HFont

Type: TYPEDEF Font map handle

HLightPrototype

Type: TYPEDEF Light prototype handle. Used to create light instances.

HMaterial

Type: TYPEDEF Material instance handle

HNamedConstantBuffer

Type: TYPEDEF Shader constant buffer handle. Holds name and values for a constant.

HRenderContext

Type: TYPEDEF The render context

HRenderItem

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.

HRenderItemDispatch

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.

HRenderListDispatch

Type: TYPEDEF Render dispatch function handle.

HSampler

Type: TYPEDEF Sampler handle

IterateNamedConstants

Type: FUNCTION Iterates over the constants

Parameters

IterateNamedConstantsFn

Type: TYPEDEF

Parameters

NewConstant

Type: FUNCTION Creates a shader program constant

Parameters

Returns

NewMaterial

Type: FUNCTION

Parameters

Returns

NewNamedConstantBuffer

Type: FUNCTION Allocates a named constant buffer

Returns

NewRenderItem

Type: 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

Returns

Examples

#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);

RegisterRenderListDispatch

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

Returns

RemoveNamedConstant

Type: FUNCTION Removes a named constant from the buffer

Parameters

RENDER_CONTEXT_NAME

Type: CONSTANT Name used when registering the render context with the engine context registry.

RenderListAlloc

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

Returns

RenderListDispatchFn

Type: TYPEDEF Render dispatch function callback.

Parameters

RenderListDispatchParams

Type: STRUCT Render dispatch function callback.

Members

RenderListEntry

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

RenderListMakeDispatch

Type: 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

Returns

RenderListOperation

Type: ENUM Render batch callback states

Members

RenderListSubmit

Type: 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

RenderListVisibilityFn

Type: TYPEDEF Render visibility function callback.

Parameters

RenderListVisibilityParams

Type: STRUCT Visibility dispatch function callback.

Members

RenderObject

Type: STRUCT Render objects represent an actual draw call

Members

RenderOrder

Type: ENUM Render order

Members

Result

Type: ENUM

Members

SetBatchKey

Type: 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

Returns

SetBoundingAABB

Type: 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

Returns

SetBoundingOBB

Type: 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

Returns

SetBoundingSphere

Type: 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

Returns

SetConstantLocation

Type: FUNCTION Sets the shader program constant location

Parameters

SetConstantType

Type: FUNCTION Sets the type of the constant

Parameters

SetConstantValues

Type: FUNCTION Sets the shader program constant values

Parameters

Returns

SetMaterial

Type: 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

Returns

SetMaterialSampler

Type: FUNCTION

Parameters

Returns

SetMaterialSampler

Type: FUNCTION

Parameters

Returns

SetMaterialTags

Type: FUNCTION

Parameters

SetNamedConstant

Type: FUNCTION Sets one or more named constants to the buffer

Parameters

SetNamedConstant

Type: 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

SetNamedConstantAtIndex

Type: FUNCTION Sets a named constant in the buffer at a specific index

Parameters

Returns

SetNamedConstants

Type: FUNCTION Sets a list of named constants to the buffer

Parameters

SetOrder

Type: 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

Returns

SetWorldTransform

Type: 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

Returns

StencilTestParams

Type: STRUCT Struct holding stencil operation setup

Members

SubmitRenderListDispatch

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

UnregisterRenderListDispatch

Type: 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

Visibility

Type: ENUM Visibility status

Members