#include <DVLCore.h>

Public Member Functions
virtual DVLRESULT	Init (IDVLClient *pDVLClient, uint32_t uVersionMajor, uint32_t uVersionMinor)=0

virtual DVLRESULT	InitRenderer ()=0

virtual DVLRESULT	DoneRenderer ()=0

virtual void	Release ()=0

virtual uint32_t	GetMajorVersion ()=0

virtual uint32_t	GetMinorVersion ()=0

virtual uint32_t	GetMicroVersion ()=0

virtual uint32_t	GetBuildNumber ()=0

virtual DVLRESULT	LoadScene (const char szURL, const char szOptionalPassword, IDVLScene *ppScene, size_t uBallastBufferSize=0, sDVLRootEntityItem pRootEntity=NULL)=0

virtual DVLRESULT	LoadSceneFromVDSL (const char content, const char password, IDVLScene *ppScene, size_t uBallastBufferSize=0, sDVLRootEntityItem pRootEntity=NULL)=0

virtual DVLRESULT	CreateEmptyScene (IDVLScene **ppScene, size_t uBallastBufferSize=0)=0

virtual DVLRESULT	RetrieveConfigurationList (const char szURL, const char szOptionalPassword, sDVLRootEntitiesInfo *listOfRootEntities)=0

virtual void	ReleaseConfigurationList (sDVLRootEntitiesInfo *pInfo)=0

virtual IDVLRenderer *	GetRendererPtr ()=0

virtual IDVLLibrary *	GetLibraryPtr ()=0

virtual void	OnLowMemory ()=0

virtual DVLRESULT	SetLocale (const char *szLocale)=0

virtual void	ExecuteCallback (void *pCallbackParam)=0

Detailed Description

This class defines the main interface for interaction with DVL.

The typical usage scheme is:

IDVLCore *pCore = DVLCreateCoreInstance();
pCore->Init(NULL, DVL_VERSION_MAJOR, DVL_VERSION_MINOR);
pCore->InitRender();
IDVLRenderer *pRenderer = pCore->GetRendererPtr();
IDVLScene *pScene = NULL;
pCore->LoadScene("file://path/to/file.vds", NULL, &pScene);
pRenderer->AttachScene(pScene);
pScene->Release();
// do something with the scene
pCore->DoneRenderer();
pCore->Release();

Member Function Documentation

§ CreateEmptyScene()

virtual DVLRESULT IDVLCore::CreateEmptyScene	(	IDVLScene **	ppScene,
		size_t	uBallastBufferSize = `0`
	)

pure virtual

Creates a new scene by loading it from the specified URL

Parameters

ppScene	Pointer to the resulted scene
uBallastBufferSize	This buffer will be allocated prior to loading the scene and released once the scene has finished loading / failed to load. Useful for IOS where it can kill the app.

Note: Call IDVLScene::Release() once finished with it; If the uBallastBufferSize is non-zero, DVL will allocate that memory as a "ballast" to release it if the IDVLCore::OnLowMemory() method is called. This prevents the iOS applications to be closed if the really large scene is loaded. 1-2 Mb is a reasonably large size for the ballast buffer.

Return values

DVLRESULT_BADARG	If szURL or ppScene is NULL
DVLRESULT_OUTOFMEMORY	If could not allocate enough RAM
DVLRESULT_FAIL	If some other error occurred

§ DoneRenderer()

virtual DVLRESULT IDVLCore::DoneRenderer ( )

pure virtual

Deletes the current renderer and releases all allocated resources

Return values

DVLRESULT_HARDWAREERROR	If some problems with OpenGL
DVLRESULT_NOTINITIALIZED	When renderer is not initialized
DVLRESULT_OK	If worked correctly

§ ExecuteCallback()

virtual void IDVLCore::ExecuteCallback ( void * pCallbackParam )

pure virtual

If DVL calls IDVLClient::RequestCallback(void *pCallbackParam) method, then the client must execute IDVLCore::ExecuteCallback() with the same "pCallbackParam" parameter as soon as possible. This technique is usually used for supporting UI updates during long operations (like LoadScene) on platforms without multithreading support.

Note: If you run ExecuteCallback() with invalid "pCallbackParam" or call it without being expplicitly requested to by DVL... then this is not treated as an error. Effectively this is a "no operation".

§ GetBuildNumber()

virtual uint32_t IDVLCore::GetBuildNumber ( )

pure virtual

Returns a build number of DVL

Note: Build number is automatically increased with each build of DVL.

§ GetLibraryPtr()

virtual IDVLLibrary* IDVLCore::GetLibraryPtr ( )

pure virtual

Returns IDVLLibrary interface

Note: It is guaranteed that GetLibraryPtr() will return the same value always, so you can save this pointer and use it directly.; It is guaranteed that GetLibraryPtr() will return a non-NULL pointer after each successfull Init().

§ GetMajorVersion()

virtual uint32_t IDVLCore::GetMajorVersion ( )

pure virtual

Returns major version of DVL

Note: Different versions of DVL with same major version are backwards-compatible with each other (see GetMinorVersion()). For example you can use DVL v4.7 on code compiled with DVL v4.5

§ GetMicroVersion()

virtual uint32_t IDVLCore::GetMicroVersion ( )

pure virtual

Returns micro version of DVL

§ GetMinorVersion()

virtual uint32_t IDVLCore::GetMinorVersion ( )

pure virtual

Returns minor version of DVL

Note: Minor version is increased every time some classes are extended, some new enums/defines added, new interfaces created, etc.; It is guaranteed that code compiled with version (MAJOR, MINOR) will be compatible with (MAJOR, MINOR+1), (MAJOR, MINOR+2), ... (MAJOR, MINOR+N).; It is guaranteed that none of existing interfaces will be truncated or removed in future versions of DVL with same Major Version.

§ GetRendererPtr()

virtual IDVLRenderer* IDVLCore::GetRendererPtr ( )

pure virtual

Returns IDVLRenderer interface

Note: It is guaranteed that GetRendererPtr() will return the same value always, so you can save this pointer and use it directly.; It is guaranteed that GetRendererPtr() will return a non-NULL pointer after each successfull InitRenderer().

§ Init()

virtual DVLRESULT IDVLCore::Init	(	IDVLClient *	pDVLClient,
		uint32_t	uVersionMajor,
		uint32_t	uVersionMinor
	)

pure virtual

Performs all class initialization and verifies that library is compatible (by checking major/minor version)

Pass a pointer to the IDVLClient derived class to be able to get the notifications from the core. Pass NULL if you don't need this.

Return values

DVLRESULT_WRONGVERSION	If version of library is not compatible with requested uVersionMajor, uVersionMinor pair
DVLRESULT_OUTOFMEMORY	When not enough RAM

Note: Must be called before any other methods of this class

§ InitRenderer()

virtual DVLRESULT IDVLCore::InitRenderer ( )

pure virtual

Performs all renderer initialization

Return values

DVLRESULT_HARDWAREERROR	If some problems with OpenGL
DVLRESULT_OUTOFMEMORY	When not enough RAM
DVLRESULT_MISSINGEXTENSION	If some OpenGL extensions are missing
DVLRESULT_NOTINITIALIZED	When Init() was not performed before InitRenderer()
DVLRESULT_ALREADYINITIALIZED	If renderer is already initialized

Note: Must be called after Init()

§ LoadScene()

virtual DVLRESULT IDVLCore::LoadScene	(	const char *	szURL,
		const char *	szOptionalPassword,
		IDVLScene **	ppScene,
		size_t	uBallastBufferSize = `0`,
		sDVLRootEntityItem *	pRootEntity = `NULL`
	)

pure virtual

Creates a new scene by loading it from the specified URL

Parameters

szURL	URL of the scene
szOptionalPassword	Only used with password-protected .vds files. If not used, set to NULL.
ppScene	Pointer to the resulted scene
uBallastBufferSize	This buffer will be allocated prior to loading the scene and released once the scene has finished loading / failed to load. Useful for IOS where it can kill the app.
pRootEntity	Pointer to the the root entity to start load the scene from. If NULL - then all configurations will be loaded.

Note: Only file URLs are currently supported (in the form of "file://path/to/file.vds"); Call IDVLScene::Release() once finished with it; If the uBallastBufferSize is non-zero, DVL will allocate that memory as a "ballast" to release it if the IDVLCore::OnLowMemory() method is called. This prevents the iOS applications to be closed if the really large scene is loaded. 1-2 Mb is a reasonably large size for the ballast buffer.

Return values

DVLRESULT_BADARG	If szURL or ppScene is NULL
DVLRESULT_OUTOFMEMORY	If could not allocate enough RAM
DVLRESULT_INTERRUPTED	If user has aborted the load process
DVLRESULT_NOTFOUND	If supplied URL is incorrect
DVLRESULT_ACCESSDENIED	If could not connect to remote server
DVLRESULT_FILENOTFOUND	If can not open file
DVLRESULT_WRONGVERSION	If file version is not supported
DVLRESULT_BADFORMAT	If the file is invalid
DVLRESULT_HARDWAREERROR	If some hardware error has happened
DVLRESULT_ENCRYPTED	If the file is encrypted and szOptionalPassword is not supplied or is incorrect
DVLRESULT_FAIL	If some other error occurred

§ LoadSceneFromVDSL()

virtual DVLRESULT IDVLCore::LoadSceneFromVDSL	(	const char *	content,
		const char *	password,
		IDVLScene **	ppScene,
		size_t	uBallastBufferSize = `0`,
		sDVLRootEntityItem *	pRootEntity = `NULL`
	)

pure virtual

Creates a new scene by loading it from the specified VDSL file

Parameters

content	Content of the VDSL file
password	Only used with password-protected .vds files. If not used, set to NULL.
ppScene	Pointer to the resulted scene
uBallastBufferSize	This buffer will be allocated prior to loading the scene and released once the scene has finished loading / failed to load. Useful for IOS where it can kill the app.
pRootEntity	Pointer to the the root entity to start load the scene from. If NULL - then all configurations will be loaded.

Note: Call IDVLScene::Release() once finished with it; If the uBallastBufferSize is non-zero, DVL will allocate that memory as a "ballast" to release it if the IDVLCore::OnLowMemory() method is called. This prevents the iOS applications to be closed if the really large scene is loaded. 1-2 Mb is a reasonably large size for the ballast buffer.

Return values

DVLRESULT_BADARG	If szURL or ppScene is NULL
DVLRESULT_OUTOFMEMORY	If could not allocate enough RAM
DVLRESULT_INTERRUPTED	If user has aborted the load process
DVLRESULT_NOTFOUND	If supplied URL is incorrect
DVLRESULT_ACCESSDENIED	If could not connect to remote server
DVLRESULT_FILENOTFOUND	If can not open file
DVLRESULT_WRONGVERSION	If file version is not supported
DVLRESULT_BADFORMAT	If the file is invalid
DVLRESULT_HARDWAREERROR	If some hardware error has happened
DVLRESULT_ENCRYPTED	If the file is encrypted and szOptionalPassword is not supplied or is incorrect
DVLRESULT_FAIL	If some other error occurred

§ OnLowMemory()

virtual void IDVLCore::OnLowMemory ( )

pure virtual

Releases internal caches and any other information that can be recreated by DVL core when necessary

This is called by the hosting environment if there's not enough free memory for the application. The function is mostly for the iOS apps and must be called if the application receives the -didReceiveMemoryWarning event.

§ Release()

virtual void IDVLCore::Release ( )

pure virtual

Deletes the core

Call this when you finish using the library. This releases all the internal structures allocated by the core.

§ ReleaseConfigurationList()

virtual void IDVLCore::ReleaseConfigurationList ( sDVLRootEntitiesInfo * pInfo )

pure virtual

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

Parameters

pInfo A pointer to the sDVLRootEntitiesInfo structure filled by the RetrieveConfigurationList() call

§ RetrieveConfigurationList()

virtual DVLRESULT IDVLCore::RetrieveConfigurationList	(	const char *	szURL,
		const char *	szOptionalPassword,
		sDVLRootEntitiesInfo *	listOfRootEntities
	)

pure virtual

Loads the list of available configurations (Root Entities) from the specified URL

Parameters

szURL	URL of the scene
szOptionalPassword	Only used with password-protected .vds files. If not used, set to NULL.
listOfRootEntities	Pointer to the resulted list of root entities

§ SetLocale()

virtual DVLRESULT IDVLCore::SetLocale ( const char * szLocale )

pure virtual

Sets locale which is used for getting text of viewports, layers, callouts, etc during file load. Default is "neutral locale". Locale format is "en-US", "de-DE" ... Use NULL or "" value to set "neutral locale".

Note: Locale setting is only used during scene load. So if you change it on the fly, then you would need to reload the file.

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

DVLCore.h

Public Member Functions

Detailed Description

Member Function Documentation

§ CreateEmptyScene()

§ DoneRenderer()

§ ExecuteCallback()

§ GetBuildNumber()

§ GetLibraryPtr()

§ GetMajorVersion()

§ GetMicroVersion()

§ GetMinorVersion()

§ GetRendererPtr()

§ Init()

§ InitRenderer()

§ LoadScene()

§ LoadSceneFromVDSL()

§ OnLowMemory()

§ Release()

§ ReleaseConfigurationList()

§ RetrieveConfigurationList()

§ SetLocale()