Resource

Functions for managing resource types.

Namespace: Resource
Include: #include <dmsdk/resource/resource.h>
TYPES
FResourceCreate Resource create function
FResourceDecrypt Encrypts a resource in-place
FResourceDestroy Resource destroy function
FResourcePostCreate Resource postcreate function
FResourcePreload Resource preloading function. This may be called f...
FResourceRecreate Resource recreate function. Recreate resource in-p...
FResourceTypeDeregister Resource type destroy function. Generally used to ...
FResourceTypeRegister Resource type setup function.
HResourceDescriptor Holds information about a currently loaded resourc...
HResourceFactory Resource factory handle. Holds references to all c...
HResourcePreloadHintInfo Holds information about preloading resources
HResourceType Represents a resource type, with a context and typ...
HResourceTypeContext Holds the resource types, as well as extra in engi...
CONSTANTS
ResourceTypeCreatorDescBufferSize Resource type creator desc byte size declaration
ENUMS
ResourceResult ResourceResult
FUNCTIONS
void FResourceReloadedCallback( params) Function called when a resource has been reloaded.
ResourceResult GetDescriptor(HResourceFactory factory, dmhash_t path, HResourceDescriptor* descriptor) Get resource descriptor from resource (name)
ResourceResult GetDescriptorByHash(HResourceFactory factory, dmhash_t path_hash, HResourceDescriptor* descriptor) Get resource descriptor from resource (name)
ResourceResult ResourceAddFile(HResourceFactory factory, const char* path, uint32_t size, const void* resource) Adds a file to the resource system Any request for...
void ResourceCreateParams() Parameters to ResourceCreate function of the resou...
dmhash_t ResourceDescriptorGetNameHash(HResourceDescriptor rd) get path hash of resource
void* ResourceDescriptorGetPrevResource(HResourceDescriptor rd) get the previous resource data
void* ResourceDescriptorGetResource(HResourceDescriptor rd) get the resource data
uint32_t ResourceDescriptorGetResourceSize(HResourceDescriptor rd) get the resource data size
HResourceType ResourceDescriptorGetType(HResourceDescriptor rd) get the resource type
void ResourceDescriptorSetPrevResource(HResourceDescriptor rd, void* resource) set the previous resource data
void ResourceDescriptorSetResource(HResourceDescriptor rd, void* resource) set the resource data
void ResourceDescriptorSetResourceSize(HResourceDescriptor rd, uint32_t size) set the resource data size
void ResourceDestroyParams() Parameters to ResourceDestroy function of the reso...
ResourceResult ResourceGet(HResourceFactory factory, const char* name, void** resource) Get a resource from factory
ResourceResult ResourceGetByHash(HResourceFactory factory, dmhash_t name, void** resource) Get a resource from factory
ResourceResult ResourceGetPath(HResourceFactory factory, void* resource, dmhash_t* hash) Returns the canonical path hash of a resource
ResourceResult ResourceGetRaw(HResourceFactory factory, dmhash_t name, void** resource, uint32_t* resource_size) Get raw resource data. Unregistered resources can ...
void ResourcePostCreateParams() Parameters to ResourcePostCreate function of the r...
bool ResourcePreloadHint(dmResource::HResourcePreloadHintInfo preloader, const char* path) Hint the preloader what to load before Create is c...
void ResourcePreloadParams() Parameters to ResourcePreload function of the reso...
void ResourceRecreateParams() Parameters to ResourceRecreate function of the res...
void ResourceRegisterDecryptionFunction(dmResource::FDecryptResource decrypt_resource) Registers a custom resource decryption function
void ResourceRelease(HResourceFactory factory, void* resource) Release resource
void ResourceReloadedParams() Parameters to ResourceReloaded function of the res...
ResourceResult ResourceRemoveFile(HResourceFactory factory, const char* path) Removes a previously registered file from the reso...
void* ResourceTypeGetContext(HResourceType type) get context from type
const char* ResourceTypeGetName(HResourceType type) get registered extension name of the type
dmhash_t ResourceTypeGetNameHash(HResourceType type) get registered extension name hash of the type
void ResourceTypeSetContext(HResourceType type, void* context) set context from type
void ResourceTypeSetCreateFn(HResourceType type, FResourceCreate fn) set create function for type
void ResourceTypeSetDestroyFn(HResourceType type, FResourceDestroy fn) set destroy function for type
void ResourceTypeSetPostCreateFn(HResourceType type, FResourcePostCreate fn) set post create function for type
void ResourceTypeSetPreloadFn(HResourceType type, FResourcePreload fn) set preload function for type
void ResourceTypeSetRecreateFn(HResourceType type, FResourceRecreate fn) set recreate function for type
MACROS
DM_DECLARE_RESOURCE_TYPE(symbol, suffix, register_fn, deregister_fn) declare a new resource type
DM_DECLARE_RESOURCE_TYPE(symbol, suffix, register_fn, deregister_fn) declare a new resource type

Functions

FResourceReloadedCallback

void FResourceReloadedCallback( params)

Function called when a resource has been reloaded.

PARAMETERS

params Parameters

GetDescriptor

ResourceResult GetDescriptor(HResourceFactory factory, dmhash_t path, HResourceDescriptor* descriptor)

Get resource descriptor from resource (name)

PARAMETERS

HResourceFactory factory Factory handle
dmhash_t path Resource path
HResourceDescriptor* descriptor Returned resource descriptor

RETURNS

ResourceResult RESULT_OK on success

GetDescriptorByHash

ResourceResult GetDescriptorByHash(HResourceFactory factory, dmhash_t path_hash, HResourceDescriptor* descriptor)

Get resource descriptor from resource (name)

PARAMETERS

HResourceFactory factory Factory handle
dmhash_t path_hash Resource path hash
HResourceDescriptor* descriptor Returned resource descriptor

RETURNS

ResourceResult RESULT_OK on success

ResourceAddFile

ResourceResult ResourceAddFile(HResourceFactory factory, const char* path, uint32_t size, const void* resource)

Adds a file to the resource system Any request for this path will go through any existing mounts first. If you wish to provide file overrides, please use the LiveUpdate feature for that. The file isn't persisted between sessions.

PARAMETERS

HResourceFactory factory Factory handle
const char* path The path of the resource
uint32_t size The size of the resource (in bytes)
const void* resource The resource payload

RETURNS

ResourceResult RESULT_OK on success

ResourceCreateParams

void ResourceCreateParams()

Parameters to ResourceCreate function of the resource type

PARAMETERS

ResourceDescriptorGetNameHash

dmhash_t ResourceDescriptorGetNameHash(HResourceDescriptor rd)

get path hash of resource

PARAMETERS

HResourceDescriptor rd The resource

RETURNS

dmhash_t The path hash

ResourceDescriptorGetPrevResource

void* ResourceDescriptorGetPrevResource(HResourceDescriptor rd)

get the previous resource data

PARAMETERS

HResourceDescriptor rd The resource handle

RETURNS

void* The resource data

ResourceDescriptorGetResource

void* ResourceDescriptorGetResource(HResourceDescriptor rd)

get the resource data

PARAMETERS

HResourceDescriptor rd The resource handle

RETURNS

void* The resource data

ResourceDescriptorGetResourceSize

uint32_t ResourceDescriptorGetResourceSize(HResourceDescriptor rd)

get the resource data size

PARAMETERS

HResourceDescriptor rd The resource handle

RETURNS

uint32_t The resource data size (in bytes)

ResourceDescriptorGetType

HResourceType ResourceDescriptorGetType(HResourceDescriptor rd)

get the resource type

PARAMETERS

HResourceDescriptor rd The resource handle

RETURNS

HResourceType The resource type

ResourceDescriptorSetPrevResource

void ResourceDescriptorSetPrevResource(HResourceDescriptor rd, void* resource)

set the previous resource data

PARAMETERS

HResourceDescriptor rd The resource handle
void* resource The resource data

ResourceDescriptorSetResource

void ResourceDescriptorSetResource(HResourceDescriptor rd, void* resource)

set the resource data

PARAMETERS

HResourceDescriptor rd The resource handle
void* resource The resource data

ResourceDescriptorSetResourceSize

void ResourceDescriptorSetResourceSize(HResourceDescriptor rd, uint32_t size)

set the resource data size

PARAMETERS

HResourceDescriptor rd The resource handle
uint32_t size The resource data size (in bytes)

ResourceDestroyParams

void ResourceDestroyParams()

Parameters to ResourceDestroy function of the resource type

PARAMETERS

ResourceGet

ResourceResult ResourceGet(HResourceFactory factory, const char* name, void** resource)

Get a resource from factory

PARAMETERS

HResourceFactory factory Factory handle
const char* name Resource name
void** resource Created resource

RETURNS

ResourceResult RESULT_OK on success

ResourceGetByHash

ResourceResult ResourceGetByHash(HResourceFactory factory, dmhash_t name, void** resource)

Get a resource from factory

PARAMETERS

HResourceFactory factory Factory handle
dmhash_t name Resource name
void** resource Created resource

RETURNS

ResourceResult RESULT_OK on success

ResourceGetPath

ResourceResult ResourceGetPath(HResourceFactory factory, void* resource, dmhash_t* hash)

Returns the canonical path hash of a resource

PARAMETERS

HResourceFactory factory Factory handle
void* resource The resource pointer
dmhash_t* hash (out) The path hash of the resource

RETURNS

ResourceResult RESULT_OK on success

ResourceGetRaw

ResourceResult ResourceGetRaw(HResourceFactory factory, dmhash_t name, void** resource, uint32_t* resource_size)

Get raw resource data. Unregistered resources can be loaded with this function. If successful, the returned resource data must be deallocated with free()

PARAMETERS

HResourceFactory factory Factory handle
dmhash_t name Resource name
void** resource Created resource
uint32_t* resource_size Resource size

RETURNS

ResourceResult RESULT_OK on success

ResourcePostCreateParams

void ResourcePostCreateParams()

Parameters to ResourcePostCreate function of the resource type

PARAMETERS

ResourcePreloadHint

bool ResourcePreloadHint(dmResource::HResourcePreloadHintInfo preloader, const char* path)

Hint the preloader what to load before Create is called on the resource. The resources are not guaranteed to be loaded before Create is called. This function can be called from a worker thread.

PARAMETERS

dmResource::HResourcePreloadHintInfo preloader Preloader handle
const char* path Resource path

RETURNS

bool if successfully invoking preloader.

ResourcePreloadParams

void ResourcePreloadParams()

Parameters to ResourcePreload function of the resource type

PARAMETERS

ResourceRecreateParams

void ResourceRecreateParams()

Parameters to ResourceRecreate function of the resource type

PARAMETERS

ResourceRegisterDecryptionFunction

void ResourceRegisterDecryptionFunction(dmResource::FDecryptResource decrypt_resource)

Registers a custom resource decryption function

PARAMETERS

dmResource::FDecryptResource decrypt_resource The decryption function

ResourceRelease

void ResourceRelease(HResourceFactory factory, void* resource)

Release resource

PARAMETERS

HResourceFactory factory Factory handle
void* resource Resource pointer

ResourceReloadedParams

void ResourceReloadedParams()

Parameters to ResourceReloaded function of the resource type

PARAMETERS

ResourceRemoveFile

ResourceResult ResourceRemoveFile(HResourceFactory factory, const char* path)

Removes a previously registered file from the resource system

PARAMETERS

HResourceFactory factory Factory handle
const char* path The path of the resource

RETURNS

ResourceResult RESULT_OK on success

ResourceTypeGetContext

void* ResourceTypeGetContext(HResourceType type)

get context from type

PARAMETERS

HResourceType type The type

RETURNS

void* 0 if no context was registered

ResourceTypeGetName

const char* ResourceTypeGetName(HResourceType type)

get registered extension name of the type

PARAMETERS

HResourceType type The type

RETURNS

const char* The name of the type (e.g. "collectionc")

ResourceTypeGetNameHash

dmhash_t ResourceTypeGetNameHash(HResourceType type)

get registered extension name hash of the type

PARAMETERS

HResourceType type The type

RETURNS

dmhash_t The name hash

ResourceTypeSetContext

void ResourceTypeSetContext(HResourceType type, void* context)

set context from type

PARAMETERS

HResourceType type The type
void* context The context to associate with the type

ResourceTypeSetCreateFn

void ResourceTypeSetCreateFn(HResourceType type, FResourceCreate fn)

set create function for type

PARAMETERS

HResourceType type The type
FResourceCreate fn Function to be called to creating the resource

ResourceTypeSetDestroyFn

void ResourceTypeSetDestroyFn(HResourceType type, FResourceDestroy fn)

set destroy function for type

PARAMETERS

HResourceType type The type
FResourceDestroy fn Function to be called to destroy the resource

ResourceTypeSetPostCreateFn

void ResourceTypeSetPostCreateFn(HResourceType type, FResourcePostCreate fn)

set post create function for type

PARAMETERS

HResourceType type The type
FResourcePostCreate fn Function to be called after creating the resource

ResourceTypeSetPreloadFn

void ResourceTypeSetPreloadFn(HResourceType type, FResourcePreload fn)

set preload function for type

PARAMETERS

HResourceType type The type
FResourcePreload fn Function to be called when loading of the resource starts

ResourceTypeSetRecreateFn

void ResourceTypeSetRecreateFn(HResourceType type, FResourceRecreate fn)

set recreate function for type

PARAMETERS

HResourceType type The type
FResourceRecreate fn Function to be called when recreating the resource

Constants

ResourceTypeCreatorDescBufferSize

Resource type creator desc byte size declaration. The registered description data passeed to ResourceRegisterTypeCreatorDesc must be of at least this size.

Types

FResourceCreate

Resource create function

FResourceDecrypt

Encrypts a resource in-place

FResourceDestroy

Resource destroy function

FResourcePostCreate

Resource postcreate function

FResourcePreload

Resource preloading function. This may be called from a separate loading thread but will not keep any mutexes held while executing the call. During this call PreloadHint can be called with the supplied hint_info handle. If RESULT_OK is returned, the resource Create function is guaranteed to be called with the preload_data value supplied.

FResourceRecreate

Resource recreate function. Recreate resource in-place.

FResourceTypeDeregister

Resource type destroy function. Generally used to destroy the registered resource type context.

FResourceTypeRegister

Resource type setup function.

HResourceDescriptor

Holds information about a currently loaded resource.

HResourceFactory

Resource factory handle. Holds references to all currently loaded resources.

HResourcePreloadHintInfo

Holds information about preloading resources

HResourceType

Represents a resource type, with a context and type functions for creation and destroying a resource.

HResourceTypeContext

Holds the resource types, as well as extra in engine contexts that can be shared across type functions.

Enums

ResourceResult

ResourceResult

RESOURCE_RESULT_OK
RESOURCE_RESULT_INVALID_DATA
RESOURCE_RESULT_DDF_ERROR
RESOURCE_RESULT_RESOURCE_NOT_FOUND
RESOURCE_RESULT_MISSING_FILE_EXTENSION
RESOURCE_RESULT_ALREADY_REGISTERED
RESOURCE_RESULT_INVAL
RESOURCE_RESULT_UNKNOWN_RESOURCE_TYPE
RESOURCE_RESULT_OUT_OF_MEMORY
RESOURCE_RESULT_IO_ERROR
RESOURCE_RESULT_NOT_LOADED
RESOURCE_RESULT_OUT_OF_RESOURCES
RESOURCE_RESULT_STREAMBUFFER_TOO_SMALL
RESOURCE_RESULT_FORMAT_ERROR
RESOURCE_RESULT_CONSTANT_ERROR
RESOURCE_RESULT_NOT_SUPPORTED
RESOURCE_RESULT_RESOURCE_LOOP_ERROR
RESOURCE_RESULT_PENDING
RESOURCE_RESULT_INVALID_FILE_EXTENSION
RESOURCE_RESULT_VERSION_MISMATCH
RESOURCE_RESULT_SIGNATURE_MISMATCH
RESOURCE_RESULT_UNKNOWN_ERROR

Macros

DM_DECLARE_RESOURCE_TYPE

Declare and register new resource type to the engine. This macro is used to declare the resource type callback functions used by the engine to communicate with the extension.

symbol external extension symbol description (no quotes).
suffix The file resource suffix, without a ".".
register_fn type register function
ctx
dmResource::ResourceTypeRegisterContext& Reference to an ResourceTypeRegisterContext structure.
deregister_fn type deregister function. May be null.
ctx
dmResource::ResourceTypeRegisterContext& Reference to an ResourceTypeRegisterContext structure.

EXAMPLES

Register a new type: 
#include <dmsdk/resource/resource_params.h>
#include <dmsdk/resource/resource_type.h>

static ResourceResult MyResourceTypeScriptCreate(const ResourceCreateParams* params) {}
static ResourceResult MyResourceTypeScriptDestroy(const ResourceDestroyParams* params) {}
static ResourceResult MyResourceTypeScriptRecreate(const ResourceRereateParams* params) {}

struct MyContext
{
    // ...
};

static ResourceResult RegisterResourceTypeBlob(HResourceTypeContext ctx, HResourceType type)
{
    // The engine.cpp creates the contexts for our built in types.
    // Here we register a custom type
    MyContext* context = new MyContext;

    ResourceTypeSetContext(type, (void*)context);
    ResourceTypeSetCreateFn(type, MyResourceTypeScriptCreate);
    ResourceTypeSetDestroyFn(type, MyResourceTypeScriptDestroy);
    ResourceTypeSetRecreateFn(type, MyResourceTypeScriptRecreate);
}

static ResourceResult DeregisterResourceTypeBlob(HResourceTypeContext ctx, HResourceType type)
{
    MyContext* context = (MyContext*)ResourceTypeGetContext(type);
    delete context;
}

DM_DECLARE_RESOURCE_TYPE(ResourceTypeBlob, "blobc", RegisterResourceTypeBlob, DeregisterResourceTypeBlob);

DM_DECLARE_RESOURCE_TYPE

Declare and register new resource type to the engine. This macro is used to declare the resource type callback functions used by the engine to communicate with the extension.

symbol external extension symbol description (no quotes).
suffix The file resource suffix, without a ".".
register_fn type register function
ctx
dmResource::ResourceTypeRegisterContext& Reference to an ResourceTypeRegisterContext structure.
deregister_fn type deregister function. May be null.
ctx
dmResource::ResourceTypeRegisterContext& Reference to an ResourceTypeRegisterContext structure.

EXAMPLES

Register a new type: 
#include <dmsdk/resource/resource_params.h>
#include <dmsdk/resource/resource_type.h>

static ResourceResult MyResourceTypeScriptCreate(const ResourceCreateParams* params) {}
static ResourceResult MyResourceTypeScriptDestroy(const ResourceDestroyParams* params) {}
static ResourceResult MyResourceTypeScriptRecreate(const ResourceRereateParams* params) {}

struct MyContext
{
    // ...
};

static ResourceResult RegisterResourceTypeBlob(HResourceTypeContext ctx, HResourceType type)
{
    // The engine.cpp creates the contexts for our built in types.
    // Here we register a custom type
    MyContext* context = new MyContext;

    ResourceTypeSetContext(type, (void*)context);
    ResourceTypeSetCreateFn(type, MyResourceTypeScriptCreate);
    ResourceTypeSetDestroyFn(type, MyResourceTypeScriptDestroy);
    ResourceTypeSetRecreateFn(type, MyResourceTypeScriptRecreate);
}

static ResourceResult DeregisterResourceTypeBlob(HResourceTypeContext ctx, HResourceType type)
{
    MyContext** context = (MyContext*)ResourceTypeGetContext(type);
    delete *context;
}

DM_DECLARE_RESOURCE_TYPE(ResourceTypeBlob, "blobc", RegisterResourceTypeBlob, DeregisterResourceTypeBlob);