#include <DVLScene.h>

Public Types
enum	eCreateNodeCopyFlags : uint16_t { COPY_CHILDREN = (1 << 0), COPY_ANIMATION = (1 << 1), FULL_COPY = 0xFFFF }

Public Member Functions
virtual DVLRESULT	RetrieveSceneInfo (uint32_t flags, sDVLSceneInfo *pInfo)=0

virtual void	ReleaseSceneInfo (sDVLSceneInfo *pInfo)=0

virtual void	GetNodeSelectionInfo (uint32_t pTotalSelectedNodesCount, uint32_t pVisibleSelectedNodesCount, uint32_t *pHiddenSelectedNodesCount)=0

virtual void	PerformAction (DVLSCENEACTION action)=0

virtual DVLRESULT	RetrieveNodeInfo (DVLID id, uint32_t flags, sDVLNodeInfo *pInfo)=0

virtual void	ReleaseNodeInfo (sDVLNodeInfo *pInfo)=0

virtual DVLRESULT	RetrieveLayerInfo (DVLID id, sDVLLayerInfo *pInfo)=0

virtual void	ReleaseLayerInfo (sDVLLayerInfo *pInfo)=0

virtual DVLRESULT	RetrieveMetadata (DVLID id, sDVLMetadataInfo *pInfo)=0

virtual void	ReleaseMetadata (sDVLMetadataInfo *pInfo)=0

virtual DVLRESULT	RetrieveVEIDs (DVLID id, sDVLVEIDInfo *pInfo)=0

virtual void	ReleaseVEIDs (sDVLVEIDInfo *pInfo)=0

virtual DVLRESULT	RetrieveThumbnail (DVLID id, sDVLImage *pThumbnail)=0

virtual void	ReleaseThumbnail (sDVLImage *pThumbnail)=0

virtual DVLRESULT	BuildPartsList (uint32_t uMaxParts, uint32_t uMaxNodesInSinglePart, uint32_t uMaxPartNameLength, eDVLPartsListType eType, eDVLPartsListSort eSort, DVLID idConsumedStep, const char szSubstring, sDVLPartsListInfo pInfo)=0

virtual void	ReleasePartsList (sDVLPartsListInfo *pInfo)=0

virtual DVLRESULT	FindNodes (eDVLFindNodeType type, eDVLFindNodeMode mode, const char str, sDVLNodeIDsArrayInfo pInfo)=0

virtual void	ReleaseNodeIDsArrayInfo (sDVLNodeIDsArrayInfo *pInfo)=0

virtual DVLRESULT	RetrieveProcedures (sDVLProceduresInfo *pInfo)=0

virtual void	ReleaseProcedures (sDVLProceduresInfo *pInfo)=0

virtual DVLRESULT	ActivateStep (DVLID id, bool bFromTheBeginning, bool bContinueToTheNext, float stepTime=-1.f)=0

virtual DVLRESULT	PauseCurrentStep ()=0

virtual DVLRESULT	ApplyLayerVisibility (DVLID id, DVLLAYERVISIBILITYACTION action=DVLLAYERVISIBILITYACTION_HIDEALL_SHOWLAYER)=0

virtual DVLID	CreateNode (DVLID idParent, const char *szNodeName=NULL, DVLID idInsertBefore=DVLID_INVALID)=0

virtual DVLID	CreateNodeCopy (DVLID idNode, DVLID idParent, eCreateNodeCopyFlags flags)=0

virtual DVLRESULT	DeleteNode (DVLID id)=0

virtual DVLRESULT	ChangeNodeFlags (DVLID id, uint32_t flags, DVLFLAGOPERATION flagop)=0

virtual DVLRESULT	SetNodeOpacity (DVLID id, float opacity)=0

virtual DVLRESULT	SetNodeHighlightColor (DVLID id, uint32_t color)=0

virtual DVLRESULT	GetNodeWorldMatrix (DVLID id, sDVLMatrix &wtm) const =0

virtual DVLRESULT	SetNodeWorldMatrix (DVLID id, const sDVLMatrix *pwtm)=0

virtual DVLRESULT	GetNodeLocalMatrix (DVLID id, sDVLMatrix &tm) const =0

virtual DVLRESULT	SetNodeLocalMatrix (DVLID id, const sDVLMatrix *ptm)=0

virtual IDVLMaterial *	GetMaterialByName (const char *name) const =0

virtual size_t	GetNodeSubmeshesCount (DVLID nodeId) const =0

virtual IDVLMaterial *	GetNodeSubmeshMaterial (DVLID nodeId, size_t index) const =0

virtual DVLRESULT	SetNodeSubmeshMaterial (DVLID nodeId, size_t index, IDVLMaterial *material)=0

virtual DVLRESULT	Execute (DVLEXECUTE type, const char *str)=0

virtual void	Retain ()=0

virtual void	Release ()=0

Detailed Description

This class defines the scene interface

Note: IDVLScene uses reference counting to manage its lifetime. Do not forget to call the Release() method when you don't need the scene.

Member Function Documentation

§ ActivateStep()

virtual DVLRESULT IDVLScene::ActivateStep	(	DVLID	id,
		bool	bFromTheBeginning,
		bool	bContinueToTheNext,
		float	stepTime = `-1.f`
	)

pure virtual

Activates a step by playing its animation. Optionally plays steps that go after this step

Parameters

id	The identifier of the step or model view to activate
bFromTheBeginning	Play step from beginning or from currently paused position
bContinueToTheNext	What to do after finishing playing the current step: play next steps or stop
stepTime	The time at which the step animation starts. Default: -1.

Return values

DVLRESULT_NOTFOUND	If Step with such ID does not exist
DVLRESULT_PROCESSED	If bFromTheBeginning is false and current step is already playing (not an error, the step just continues to play)
DVLRESULT_INVALIDCALL	If bFromTheBeginning is false, bContinueToTheNext is true and current step has stopped playing and doesn't have next step (i.e. we're at the end of all steps)
DVLRESULT_OK	If a step was activated

Notes

If bFromTheBeginning is false and current step is not the same as id, then bFromTheBeginning is treated as true
If current step has finished playing and id points to current step, then one of the three things happen:
If bContinueToTheNext is true and next step exists, then next step is activated
If bContinueToTheNext is true and next step doesn't exist, then DVLRESULT_INVALIDCALL is returned
If bContinueToTheNext is false then current step is played again from the start (as if bFromTheBeginning is true)

§ ApplyLayerVisibility()

virtual DVLRESULT IDVLScene::ApplyLayerVisibility	(	DVLID	id,
		DVLLAYERVISIBILITYACTION	action = `DVLLAYERVISIBILITYACTION_HIDEALL_SHOWLAYER`
	)

pure virtual

Hides all nodes in the scene and then shows only nodes that exist in the given layer

Parameters

id	The identifier of the layer

Return values

DVLRESULT_NOTFOUND	If Layer with such ID does not exist
DVLRESULT_OK	If operation was successfully performed

§ BuildPartsList()

virtual DVLRESULT IDVLScene::BuildPartsList	(	uint32_t	uMaxParts,
		uint32_t	uMaxNodesInSinglePart,
		uint32_t	uMaxPartNameLength,
		eDVLPartsListType	eType,
		eDVLPartsListSort	eSort,
		DVLID	idConsumedStep,
		const char *	szSubstring,
		sDVLPartsListInfo *	pInfo
	)

pure virtual

Builds a parts list and stores it inside the provided structure

Note: Some files have a built-in "parts list" information. If this info exists, then this function uses existing "parts list" data structures to populate sDVLPartsListInfo. However, if explicit "parts list" info does not exist in the given file, then it is generated on the fly by combining nodes with equal names into a single part.

Parameters

uMaxParts	Maximum number of parts required. For example, it doesn't make sense to have 100,000 parts on iPad. 0 for unlimited.
uMaxNodesInSinglePart	Maximum number of nodes in a single part to be saved. If more nodes belong to a part, they will be ignored. For example, more than 1000 nodes per part is probably more than enough for iPad. 0 for unlimited.
uMaxPartNameLength	Maximum length of part name. For example, no point in having 1000 symbol strings on iPad (cause there is no way to display them anyways). 0 for unlimited.
eType	Type of listing: full, visible only, only consumed by idConsumedStep step
eSort	Type of sorting: A..Z, Z..A, etc
idConsumedStep	Only used when eType == DVLPARTSLISTTYPE_CONSUMED_BY_STEP, set to DVLID_INVALID or any other value if not DVLPARTSLISTTYPE_CONSUMED_BY_STEP
szSubstring	Only parts that include szSubstring are returned. Set to NULL if filtering is not required.
pInfo	A pointer to a sDVLPartsListInfo structure that receives the data

Return values

DVLRESULT_BADFORMAT	If m_uSizeOfDVLPartsListInfo is wrong
DVLRESULT_BADARG	If pInfo == NULL
DVLRESULT_BADARG	If eType == DVLPARTSLISTTYPE_CONSUMED_BY_STEP and idConsumedStep == DVLID_INVALID
DVLRESULT_OUTOFMEMORY	If parts list could not be created due to memory failure
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_OK	If all went fine

Notes

This call may be expensive!!! Draw hourglass cursor or something like that.
Scenes may be huge (millions of nodes), it may be a good idea to set the appropriate limitations for the list
You need to initialize the m_uSizeOfDVLPartsListInfo member with the size of the sDVLPartsListInfo structure
Use ReleasePartsList() method to release the data

Example

sDVLPartsListInfo pl = {};
pl.m_uSizeOfDVLPartsListInfo = sizeof(pl);
if (DVLSUCCEEDED(pScene->BuildPartsList(
                    DVLPARTSLIST_RECOMMENDED_uMaxParts,             // use recommended list length limit
                    DVLPARTSLIST_RECOMMENDED_uMaxNodesInSinglePart, // use recommended nodes in the part limit
                    DVLPARTSLIST_UNLIMITED_uMaxPartNameLength,      // do not limit the length of the name
                    DVLPARTSLISTTYPE_ALL,                           // build the list using all the nodes
                    DVLPARTSLISTSORT_NAME_ASCENDING,                // sort the list ascending
                    DVLID_INVALID,                                  // do not provide a consumed step id
                    NULL,                                           // do not filter
                    &pl)))
{
    printf("There are %d parts in the list\n", pl.m_uPartsCount);
    for (uint32_t i = 0; i < pl.m_uPartsCount; i++)
    {
        sDVLPartListItem *item = pl.m_pParts[i];
        printf("%d. name = '%s', has %d nodes\n", i, item->m_szName, item->m_uNodesCount);
    }
    pScene->ReleasePartsList(&pl);
}

§ ChangeNodeFlags()

virtual DVLRESULT IDVLScene::ChangeNodeFlags	(	DVLID	id,
		uint32_t	flags,
		DVLFLAGOPERATION	flagop
	)

pure virtual

Changes some node flags

Parameters

id	DVLID of the node that you need to change flags on
flags	Bitfield combination of one or more DVLNODEFLAG flags
flagop	DVLFLAGOP_SET, DVLFLAGOP_CLEAR, DVLFLAGOP_INVERT possibly ORed with DVLFLAGOP_MODIFIER_RECURSIVE

Return values

DVLRESULT_NOINTERFACE	If "id" is pointing to an item of different type
DVLRESULT_PROCESSED	If flags were not changed (not an error, DVLSUCCEEDED(DVLRESULT_PROCESSED) == true). For example when hiding a hidden node
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_OK	If some flags were changed

§ CreateNode()

virtual DVLID IDVLScene::CreateNode	(	DVLID	idParent,
		const char *	szNodeName = `NULL`,
		DVLID	idInsertBefore = `DVLID_INVALID`
	)

pure virtual

Creates an empty node in the scene. You can use this method for building node hierarchies using API.

Parameters

idParent	Parent node id. If set to DVLID_INVALID, then the node would be created at top level in hierarchy.
szNodeName	Name of the newly created node, can be NULL
idInsertBefore	The id of the node before which to insert the new node. If set to DVLID_INVALID then add the node at the end.

Return values

DVLID Created node id or DVLID_INVALID in case of error

§ CreateNodeCopy()

virtual DVLID IDVLScene::CreateNodeCopy	(	DVLID	idNode,
		DVLID	idParent,
		eCreateNodeCopyFlags	flags
	)

pure virtual

Creates node copy

Parameters

idNode	Copied node id
idParent	Parent node id
flags	Copy flags

Return values

DVLID Created node id

§ DeleteNode()

virtual DVLRESULT IDVLScene::DeleteNode ( DVLID id )

pure virtual

Deletes a node and all of its children. Works only with nodes that were previously created via API (CreateNode() and CreateNodeCopy() methods).

Parameters

id	Id of the node to delete

Return values

DVLRESULT_FAIL	If "id" is incorrect
DVLRESULT_ACCESSDENIED	If node was loaded from a .vds file. You can only delete nodes created using API.
DVLRESULT_NOTFOUND	If node with specified "id" doesn't exist
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_OK	If node and all its children were deleted

§ Execute()

virtual DVLRESULT IDVLScene::Execute	(	DVLEXECUTE	type,
		const char *	str
	)

pure virtual

Executes a query

Parameters

type	Query type, see DVLEXECUTE enum
str	Query string, see DVLEXECUTE enum for string format

Return values

DVLRESULT_FAIL	If query wasn't performed
DVLRESULT_OK	If query was successfully performed
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized

§ FindNodes()

virtual DVLRESULT IDVLScene::FindNodes	(	eDVLFindNodeType	type,
		eDVLFindNodeMode	mode,
		const char *	str,
		sDVLNodeIDsArrayInfo *	pInfo
	)

pure virtual

Finds a list of scene nodes by matching them using a string parameter [different search types are possible: by name, asset id or unique id]

Parameters

type	One of eDVLFindNodeType values
mode	One of eDVLFindNodeMode values
str	String identifier to search on (depends on "type" value)
pInfo	A pointer to the sDVLNodeIDsArrayInfo structure that receives the list of found nodes

Return values

DVLRESULT_BADARG	If pInfo == NULL
DVLRESULT_BADFORMAT	If m_uSizeOfDVLFindNodesList is wrong
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_PROCESSED	If scene does not have nodes which satisfy a query
DVLRESULT_OK	If some nodes have been retrieved

§ GetNodeLocalMatrix()

virtual DVLRESULT IDVLScene::GetNodeLocalMatrix	(	DVLID	id,
		sDVLMatrix &	tm
	)		const

pure virtual

Retrieves node local matrix

Parameters

id	DVLID of the node
tm	Node local matrix will be put into this variable

Return values

DVLRESULT_FAIL	If "id" is incorrect
DVLRESULT_NOTFOUND	If node with specified "id" doesn't exist
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_OK	If matrix was successfully retrieved

§ GetNodeSelectionInfo()

virtual void IDVLScene::GetNodeSelectionInfo	(	uint32_t *	pTotalSelectedNodesCount,
		uint32_t *	pVisibleSelectedNodesCount,
		uint32_t *	pHiddenSelectedNodesCount
	)

pure virtual

Used for quick interrogation of "node selection", for example "Show selected nodes" is only available if there is at least 1 invisible node selected

Parameters

pTotalSelectedNodesCount	Pointer to the total number of selected nodes. Set to NULL if not needed.
pVisibleSelectedNodesCount	Pointer to the number of visible selected nodes. Set to NULL if not needed.
pHiddenSelectedNodesCount	Pointer to the number of hidden selected nodes. Set to NULL if not needed.

§ GetNodeWorldMatrix()

virtual DVLRESULT IDVLScene::GetNodeWorldMatrix	(	DVLID	id,
		sDVLMatrix &	wtm
	)		const

pure virtual

Retrieves node world matrix

Parameters

id	DVLID of the node
wtm	Node world matrix will be put into this variable

Note: This matrix is re-evaluated every frame during animation.; If you specify matrix via SetNodeWorldMatrix() [i.e. set the "global" override matrix], it will override node matrix and animation until SetNodeWorldMatrix(id, NULL) is performed.; If SetNodeWorldMatrix() was not called on this node, then this method returns the world matrix which is built from scene hierarchy (using local matrices of the nodes).

Example

sDVLMatrix mat;
g_pScene->GetNodeWorldMatrix(id, mat);
mat.m[3][2] += 1.f;//Z up
g_pScene->SetNodeWorldMatrix(id, &mat);

Return values

DVLRESULT_FAIL	If "id" is incorrect
DVLRESULT_NOTFOUND	If node with specified "id" doesn't exist
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_OK	If matrix was successfully retrieved

§ PauseCurrentStep()

virtual DVLRESULT IDVLScene::PauseCurrentStep ( )

pure virtual

Pauses the current step, if any

Return values

DVLRESULT_PROCESSED	If current step is already paused (in this case it is still kept paused)
DVLRESULT_NOTFOUND	If there is no "current step" playing
DVLRESULT_OK	If current step was paused

§ PerformAction()

virtual void IDVLScene::PerformAction ( DVLSCENEACTION action )

pure virtual

Executes a particular action on the scene, see DVLSCENEACTION enum

Example

pScene->PerformAction(DVLSCENEACTION_SHOW_ALL);

pScene->PerformAction(DVLSCENEACTION_HIDE_SELECTED);

§ Release()

virtual void IDVLScene::Release ( )

pure virtual

Releases the scene and deletes it if reference count is zero.

See Retain() method for more details on reference counting.

§ ReleaseLayerInfo()

virtual void IDVLScene::ReleaseLayerInfo ( sDVLLayerInfo * pInfo )

pure virtual

Releases all memory that was initialized in a previous call to RetrieveLayerInfo()

Parameters

pInfo A pointer to a sDVLLayerInfo structure filled by RetrieveLayerInfo() call

Note: If m_uSizeOfDVLLayerInfo is wrong, pInfo will not be deleted (and you'll get a memory leak)

§ ReleaseMetadata()

virtual void IDVLScene::ReleaseMetadata ( sDVLMetadataInfo * pInfo )

pure virtual

Releases all memory that was initialized in a previous call to RetrieveMetadata()

Parameters

pInfo A pointer to the sDVLMetadataInfo structure filled by the RetrieveMetadata() call

Note: If m_uSizeOfDVLMetadata is wrong, pInfo will not be deleted (and you'll get a memory leak)

§ ReleaseNodeIDsArrayInfo()

virtual void IDVLScene::ReleaseNodeIDsArrayInfo ( sDVLNodeIDsArrayInfo * pInfo )

pure virtual

Releases all memory that was allocated by SDK in the provided pInfo structure (For example after using FindNodes())

Parameters

pInfo A pointer to a sDVLNodeIDsArrayInfo structure

Note: If m_uSizeOfDVLFindNodesList is wrong, pInfo will not be deleted (and you'll get a memory leak)

§ ReleaseNodeInfo()

virtual void IDVLScene::ReleaseNodeInfo ( sDVLNodeInfo * pInfo )

pure virtual

Releases all memory that was initialized in a previous call to RetrieveNodeInfo()

Parameters

pInfo A pointer to the sDVLNodeInfo structure filled by the RetrieveNodeInfo() call

Note: If m_uSizeOfDVLNodeInfo is wrong, pInfo will not be deleted (and you'll get a memory leak)

§ ReleasePartsList()

virtual void IDVLScene::ReleasePartsList ( sDVLPartsListInfo * pInfo )

pure virtual

Releases all memory that was initialized in a previous call to BuildPartsList()

Parameters

pInfo A pointer to a sDVLPartsListInfo structure filled by a previous BuildPartsList() call

Note: If m_uSizeOfDVLPartsListInfo is wrong, pInfo will not be deleted (and you'll get a memory leak)

§ ReleaseProcedures()

virtual void IDVLScene::ReleaseProcedures ( sDVLProceduresInfo * pInfo )

pure virtual

Releases all memory that was initialized in a previous call to RetrieveSteps()

Parameters

pInfo A pointer to a sDVLProceduresInfo structure filled by the RetrieveSteps() call

Note: If m_uSizeOfDVLProceduresInfo is wrong, pInfo will not be deleted (and you'll get a memory leak)

§ ReleaseSceneInfo()

virtual void IDVLScene::ReleaseSceneInfo ( sDVLSceneInfo * pInfo )

pure virtual

Releases all memory that was initialized in a previous call to RetrieveSceneInfo()

Parameters

pInfo A pointer to a sDVLSceneInfo structure filled by RetrieveSceneInfo() call

Note: If m_uSizeOfDVLSceneInfo is wrong, pInfo will not be deleted (and you'll get a memory leak)

§ ReleaseThumbnail()

virtual void IDVLScene::ReleaseThumbnail ( sDVLImage * pThumbnail )

pure virtual

Releases all memory that was initialized in a previous call to RetrieveThumbnail()

Parameters

pThumbnail A pointer to a sDVLImage structure filled by the RetrieveThumbnail() call

Note: If m_uSizeOfDVLThumbnail is wrong, pThumbnail will not be deleted (and you'll get a memory leak)

§ ReleaseVEIDs()

virtual void IDVLScene::ReleaseVEIDs ( sDVLVEIDInfo * pInfo )

pure virtual

Releases all memory that was initialized in a previous call to RetrieveVEIDs()

Parameters

pInfo A pointer to the sDVLVEIDInfo structure filled by the RetrieveVEIDs() call

Note: If m_uSizeOfDVLVEID is wrong, pInfo will not be deleted (and you'll get a memory leak)

§ Retain()

virtual void IDVLScene::Retain ( )

pure virtual

Increases the internal reference counter

The scene object maintains a counter of references to itself. Each Retain() call increments it, each Release() call decrements. The scene gets deleted when the counter becomes zero. When you load a scene, the counter is set to 1. You then need to call Release() to delete the scene. However, if you attach the scene to a renderer, it will keep its own reference, so your Release() call will not delete the scene unless the renderer releases it, as well.

§ RetrieveLayerInfo()

virtual DVLRESULT IDVLScene::RetrieveLayerInfo	(	DVLID	id,
		sDVLLayerInfo *	pInfo
	)

pure virtual

Retrieves layer information into the provided structure

Parameters

id	DVLID of the layer that you query on
pInfo	A pointer to the sDVLLayerInfo structure that receives the data

§ RetrieveMetadata()

virtual DVLRESULT IDVLScene::RetrieveMetadata	(	DVLID	id,
		sDVLMetadataInfo *	pInfo
	)

pure virtual

Retrieves metadata into the provided structure

Parameters

id	DVLID of the item that you query on (can be node, layer, step view)
pInfo	A pointer to the sDVLMetadataInfo structure that receives the data

Return values

DVLRESULT_BADFORMAT	If m_uSizeOfDVLMetadata is wrong
DVLRESULT_BADARG	If pInfo == NULL
DVLRESULT_OUTOFMEMORY	If metadata data could not be created due to memory failure
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_PROCESSED	If item does not have metadata (in such case sDVLMetadataInfo::m_pMetadata == NULL)
DVLRESULT_OK	If some metadata has been retrieved

Notes

You need to initialize the m_uSizeOfDVLMetadata member of the sDVLMetadataInfo structure before calling the function.
Use ReleaseMetadata() to release memory of the structure

Example

DVLID nodeId = ....; // get a node id somehow, for example via RetrieveSceneInfo()
sDVLMetadataInfo mi = {};
mi.m_uSizeOfDVLMetadata = sizeof(mi);
if (DVLSUCCEEDED(pScene->RetrieveMetadata(nodeId, &mi)))
{
    sDVLMetadata *pRoot = mi.m_pMetadata;
    if (pRoot)
        printf("The root medatadata has %d keys and %d namespaces\n", pRoot->m_uNameValuePairsCount, pRoot->m_uNamespacesCount);
    else
        printf("The node doesn't have any metadata\n");
    pScene->ReleaseMetadata(&mi);
}

§ RetrieveNodeInfo()

virtual DVLRESULT IDVLScene::RetrieveNodeInfo	(	DVLID	id,
		uint32_t	flags,
		sDVLNodeInfo *	pInfo
	)

pure virtual

Retrieves node information into the provided structure

Parameters

id	DVLID of the node that you query on
flags	Bitfield combination of one or more DVLNODEINFO flags
pInfo	A pointer to the sDVLNodeInfo structure that receives the data

Return values

DVLRESULT_BADFORMAT	If m_uSizeOfDVLNodeInfo is wrong
DVLRESULT_BADARG	If pInfo == NULL
DVLRESULT_NOINTERFACE	If "id" is pointing to an item of different type
DVLRESULT_OUTOFMEMORY	If some info could not be retrieved due to memory failure
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized

Notes

You need to initialize the m_uSizeOfDVLNodeInfo member of the sDVLNodeInfo structure with its size.
This method may be quite expensive
Try to limit the number of RetrieveNodeInfo() calls
Retrieve all info that you need in a single call with multiple flags set (it's faster than issuing multiple calls with less flags)

Example

DVLID nodeId = ....; // get a node id somehow, for example via RetrieveSceneInfo()
sDVLNodeInfo ni = {};
ni.m_uSizeOfDVLNodeInfo = sizeof(ni);
if (DVLSUCCEEDED(pScene->RetrieveNodeInfo(nodeId, DVLNODEINFO_NAME | DVLNODEINFO_CHILDREN, &ni)))
{
    printf("node '%s' has %d children\n", ni.m_szNodeName, ni.m_uChildNodesCount);
    for (uint32_t i = 0; i < ni.m_uChildNodesCount; i++)
    {
        DVLID childId = ni.m_pChildNodes[i];
        // do something with childId
    }
    // release the data
    pScene->ReleaseNodeInfo(&ni);
}

§ RetrieveProcedures()

virtual DVLRESULT IDVLScene::RetrieveProcedures ( sDVLProceduresInfo * pInfo )

pure virtual

Retrieves a list of procedures and portfolios in the scene

Parameters

pInfo A pointer to a sDVLProceduresInfo structure that receives the data

Return values

DVLRESULT_BADFORMAT	If m_uSizeOfDVLProceduresInfo is wrong
DVLRESULT_BADARG	If pInfo == NULL
DVLRESULT_OUTOFMEMORY	In case of memory failure
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_OK	If all went fine

Notes

You need to initialize the m_uSizeOfDVLProceduresInfo member of the structure with its size
Use ReleaseProcedures() to release the data
Both procedures and portfolios use the same sDVLProcedure structure

Example

sDVLProceduresInfo procs = {};
procs.m_uSizeOfDVLProceduresInfo = sizeof(procs);
if (DVLSUCCEEDED(pScene->RetrieveProcedures(&procs)))
{
    printf("The scene has %d procedures and %d portfolios\n", procs.m_uProceduresCount, procs.m_uPortfoliosCount);
    for (uint32_t i = 0; i < procs.m_uProceduresCount; i++)
    {
        sDVLProcedure *p = procs.m_pProcedures[i];
        printf("procedure #%d: name = '%s', steps = %d\n", i, p->m_szName, p->m_uStepsCount);
    }
    for (uint32_t i = 0; i < procs.m_uPortfoliosCount; i++)
    {
        sDVLProcedure *p = procs.m_pPortfolios[i];
        printf("portfolio #%d: name = '%s', model views = %d\n", i, p->m_szName, p->m_uStepsCount);
    }
    pScene->ReleaseProcedures(&procs);
}

§ RetrieveSceneInfo()

virtual DVLRESULT IDVLScene::RetrieveSceneInfo	(	uint32_t	flags,
		sDVLSceneInfo *	pInfo
	)

pure virtual

Retrieves scene information into the provided structure

Parameters

flags	Bitfield combination of one or more DVLSCENEINFO flags
pInfo	A pointer to the sDVLSceneInfo structure that receives the scene information

Return values

DVLRESULT_BADFORMAT	If m_uSizeOfDVLSceneInfo is wrong
DVLRESULT_BADARG	If pInfo == NULL
DVLRESULT_OUTOFMEMORY	If some info could not be retrieved due to memory failure
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized

Notes

You need to initialize the m_uSizeOfDVLSceneInfo member of the sDVLSceneInfo structure with its size.
This method may be quite expensive
Try to limit the number of RetrieveSceneInfo() calls
Retrieve all info that you need in a single call with multiple flags set (it's faster than issuing multiple calls with less flags)

Example

sDVLSceneInfo si = {};
si.m_uSizeOfDVLSceneInfo = sizeof(si);
if (DVLSUCCEEDED(pScene->RetrieveSceneInfo(DVLSCENEINFO_SELECTED | DVLSCENEINFO_CHILDREN, &si)))
{
    printf("%d nodes selected, %d top level items\n", si.m_uSelectedNodesCount, si.m_uChildNodesCount);
    for (uint32_t i = 0; i < si.m_uSelectedNodesCount; i++)
    {
        DVLID selId = si.m_pSelectedNodes[i];
        // do something with selId
    }
    for (uint32_t i = 0; i < si.m_uChildNodesCount; i++)
    {
        DVLID childId = si.m_pChildNodes[i];
        // do something with childId
    }
    // release the data
    pScene->ReleaseSceneInfo(&si);
}

§ RetrieveThumbnail()

virtual DVLRESULT IDVLScene::RetrieveThumbnail	(	DVLID	id,
		sDVLImage *	pThumbnail
	)

pure virtual

Retrieves a thumbnail for specified DVLID into the provided buffer

Parameters

id	DVLID of an item (item type may be arbitrary)
pThumbnail	A pointer to the sDVLImage structure that receives the data.

Return values

DVLRESULT_BADFORMAT	If m_uSizeOfDVLMetadata is wrong
DVLRESULT_BADARG	If pInfo == NULL
DVLRESULT_OUTOFMEMORY	If thumbnail could not be retrieved due to memory failure
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_NOTFOUND	If item does not have thumbnail (in such case sDVLImage::m_pImageBuffer == NULL)
DVLRESULT_OK	If thumbnail was successfully retrieved

Notes

Most item types don't have thumbnails
The data you receive are encoded (either JPEG or PNG), so you have to decode them first. This needs to be done using the OS-specific routines.

Example

DVLID stepId = ...; // get a step identifier somehow
sDVLImage img = {};
img.m_uSizeOfDVLImage = sizeof(img);
if (DVLSUCCEEDED(pScene->RetrieveThumbnail(stepId, &img)))
{
    LoadImageFromData(img.m_uImageSize, img.m_pImageBuffer); // use the image data
    pScene->ReleaseThumbnail(&mi);
}

§ RetrieveVEIDs()

virtual DVLRESULT IDVLScene::RetrieveVEIDs	(	DVLID	id,
		sDVLVEIDInfo *	pInfo
	)

pure virtual

Retrieves VEIDs into the provided structure.

Parameters

id	DVLID of the item that you query on
pInfo	A pointer to the sDVLVEIDInfo structure that receives the data

Return values

DVLRESULT_BADFORMAT	If m_uSizeOfDVLVEID is wrong
DVLRESULT_BADARG	If pInfo == NULL
DVLRESULT_OUTOFMEMORY	If VEID data could not be created due to memory failure
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_PROCESSED	If item does not have VEIDs (in such case sDVLVEIDInfo::m_pIDs == NULL)
DVLRESULT_OK	If VEIDs have been retrieved

Notes

You need to initialize the m_uSizeOfDVLVEID member of the sDVLVEIDInfo structure before calling the function.
Use ReleaseVEIDs() to release memory of the structure

§ SetNodeHighlightColor()

virtual DVLRESULT IDVLScene::SetNodeHighlightColor	(	DVLID	id,
		uint32_t	color
	)

pure virtual

Sets node highlight color

Parameters

id	DVLID of the node that you need to set highlight color for
color	Highlight color value (32-bit ABGR, where A is amount of blending between material color and highlight color)

Note: Make sure you set 'A' component to non-zero value, or otherwise highlight will not be visible (as the amount would be '0'). For example, 0xFF0000FF gives 100% red highlight. 0x7F00FF00 gives 50% green highlight.; Set "color" to 0 to clear highlighting

Return values

DVLRESULT_FAIL	If "id" is incorrect
DVLRESULT_NOTFOUND	If node with specified "id" doesn't exist
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_OK	If node highlight color was modified

§ SetNodeLocalMatrix()

virtual DVLRESULT IDVLScene::SetNodeLocalMatrix	(	DVLID	id,
		const sDVLMatrix *	ptm
	)

pure virtual

Sets node local matrix

Parameters

id	DVLID of the node
ptm	Pointer to a local matrix to set. Set to NULL if you want to remove local matrix (if local matrix does not exist, it is treated as Identity matrix in all computations).

Note: Local matrix modification is only allowed on nodes that were created using API methods. It is not allowed on nodes that came from a .vds file.

Return values

DVLRESULT_FAIL	If "id" is incorrect
DVLRESULT_ACCESSDENIED	If node was loaded from a .vds file. Local matrix modification is only allowed on nodes created via API.
DVLRESULT_NOTFOUND	If node with specified "id" doesn't exist
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_OK	If matrix was successfully modified

§ SetNodeOpacity()

virtual DVLRESULT IDVLScene::SetNodeOpacity	(	DVLID	id,
		float	opacity
	)

pure virtual

Sets node opacity

Parameters

id	DVLID of the node that you need to set opacity
opacity	Opacity amount (0.0 - fully transparent, 1.0 - fully opaque)

Return values

DVLRESULT_FAIL	If "id" is incorrect
DVLRESULT_NOTFOUND	If node with specified "id" doesn't exist
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_OK	If node opacity was modified

§ SetNodeWorldMatrix()

virtual DVLRESULT IDVLScene::SetNodeWorldMatrix	(	DVLID	id,
		const sDVLMatrix *	pwtm
	)

pure virtual

Sets node world matrix

Parameters

id	DVLID of the node
pwtm	Pointer to a world matrix to set. Set to NULL if you want to restore default matrix.

Note: If you set matrix with this call, it will override node matrix evaluation in DVL until SetNodeWorldMatrix(id, NULL) is performed. I.e. animation for this node will not play.; Technical detail: this fills in a special "global" matrix for a node which takes precedense over node local matrix and animation.

Example

sDVLMatrix mat;
g_pScene->GetNodeWorldMatrix(id, mat);
mat.m[3][2] += 1.f;//Z up
g_pScene->SetNodeWorldMatrix(id, &mat);

Return values

DVLRESULT_FAIL	If "id" is incorrect
DVLRESULT_NOTFOUND	If node with specified "id" doesn't exist
DVLRESULT_NOTINITIALIZED	If scene is not properly initialized
DVLRESULT_OK	If matrix was successfully modified

The documentation for this class was generated from the following file:

DVLScene.h

Public Types

Public Member Functions

Detailed Description

Member Function Documentation

§ ActivateStep()

§ ApplyLayerVisibility()

§ BuildPartsList()

§ ChangeNodeFlags()

§ CreateNode()

§ CreateNodeCopy()

§ DeleteNode()

§ Execute()

§ FindNodes()

§ GetNodeLocalMatrix()

§ GetNodeSelectionInfo()

§ GetNodeWorldMatrix()

§ PauseCurrentStep()

§ PerformAction()

§ Release()

§ ReleaseLayerInfo()

§ ReleaseMetadata()

§ ReleaseNodeIDsArrayInfo()

§ ReleaseNodeInfo()

§ ReleasePartsList()

§ ReleaseProcedures()

§ ReleaseSceneInfo()

§ ReleaseThumbnail()

§ ReleaseVEIDs()

§ Retain()

§ RetrieveLayerInfo()

§ RetrieveMetadata()

§ RetrieveNodeInfo()

§ RetrieveProcedures()

§ RetrieveSceneInfo()

§ RetrieveThumbnail()

§ RetrieveVEIDs()

§ SetNodeHighlightColor()

§ SetNodeLocalMatrix()

§ SetNodeOpacity()

§ SetNodeWorldMatrix()