Resource

Functions for managing resource types.

Namespace: dmResource
Include: #include <dmsdk/resource/resource.hpp>
TYPES
FDecryptResource Decrypts a file
FResourceDecrypt Encrypts a resource in-place
HDescriptor Holds information about a currently loaded resourc...
HFactory Resource factory handle. Holds references to all c...
HPreloadHintInfo Holds information about preloading resources
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...
ENUMS
ResourceResult ResourceResult
Result ResourceResult
FUNCTIONS
ResourceResult AddFile(HResourceFactory factory, const char* path, uint32_t size, const void* resource) Adds a file to the resource system Any request for...
dmResource::Result AddFile(dmResource::HFactory factory, const char* path, uint32_t size, const void* resource) Adds a file to the resource system Any request for...
void FReloadedCallback( params) Function called when a resource has been reloaded.
void FResourceReloadedCallback( params) Function called when a resource has been reloaded.
ResourceResult Get(HResourceFactory factory, const char* name, void** resource) Get a resource from factory
dmResource::Result Get(dmResource::HFactory factory, const char* name, void** resource) Get a resource from factory
dmResource::Result Get(dmResource::HFactory factory, dmhash_t name, void** resource) Get a resource from factory
ResourceResult GetByHash(HResourceFactory factory, dmhash_t name, void** resource) Get a resource from factory
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 GetPath(HResourceFactory factory, void* resource, dmhash_t* hash) Returns the canonical path hash of a resource
ResourceResult GetRaw(HResourceFactory factory, dmhash_t name, void** resource, uint32_t* resource_size) Get raw resource data. Unregistered resources can ...
bool PreloadHint(dmResource::HResourcePreloadHintInfo preloader, const char* path) Hint the preloader what to load before Create is c...
bool PreloadHint(dmResource::HResourcePreloadHintInfo factory, const char* name) Hint the preloader what to load before Create is c...
void RegisterResourceDecryptionFunction(dmResource::FDecryptResource decrypt_resource) Registers a custom resource decryption function
void RegisterType()
void Release(HResourceFactory factory, void* resource) Release resource
void Release(dmResource::HFactory factory, void* resource) Release resource
ResourceResult RemoveFile(HResourceFactory factory, const char* path) Removes a previously registered file from the reso...
dmResource::Result RemoveFile(dmResource::HFactory factory, const char* path) Removes a previously registered file from the reso...
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...
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...
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 ResourceTypeCreatorDescBufferSize() Resource type creator desc byte size declaration
void SetupType() Setup function pointers and context for a resource...
MACROS
DM_DECLARE_RESOURCE_TYPE() declare a new resource type

Functions

AddFile

ResourceResult AddFile(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

AddFile

dmResource::Result AddFile(dmResource::HFactory 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

dmResource::HFactory 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

dmResource::Result on success.

FReloadedCallback

void FReloadedCallback( params)

Function called when a resource has been reloaded.

PARAMETERS

params Parameters

FResourceReloadedCallback

void FResourceReloadedCallback( params)

Function called when a resource has been reloaded.

PARAMETERS

params Parameters

Get

ResourceResult Get(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

Get

dmResource::Result Get(dmResource::HFactory factory, const char* name, void** resource)

Get a resource from factory

PARAMETERS

dmResource::HFactory factory Factory handle
const char* name Resource name
void** resource Created resource

RETURNS

dmResource::Result RESULT_OK on success

Get

dmResource::Result Get(dmResource::HFactory factory, dmhash_t name, void** resource)

Get a resource from factory

PARAMETERS

dmResource::HFactory factory Factory handle
dmhash_t name Resource name
void** resource Created resource

RETURNS

dmResource::Result RESULT_OK on success

GetByHash

ResourceResult GetByHash(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

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

GetPath

ResourceResult GetPath(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

GetRaw

ResourceResult GetRaw(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

PreloadHint

bool PreloadHint(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.

PreloadHint

bool PreloadHint(dmResource::HResourcePreloadHintInfo factory, const char* name)

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 factory Preloader handle
const char* name Resource name

RETURNS

bool if successfully invoking preloader.

RegisterResourceDecryptionFunction

void RegisterResourceDecryptionFunction(dmResource::FDecryptResource decrypt_resource)

Registers a custom resource decryption function

PARAMETERS

dmResource::FDecryptResource decrypt_resource The decryption function

RegisterType

void RegisterType()

PARAMETERS


Release

void Release(HResourceFactory factory, void* resource)

Release resource

PARAMETERS

HResourceFactory factory Factory handle
void* resource Resource pointer

Release

void Release(dmResource::HFactory factory, void* resource)

Release resource

PARAMETERS

dmResource::HFactory factory Factory handle
void* resource Resource pointer

RemoveFile

ResourceResult RemoveFile(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

RemoveFile

dmResource::Result RemoveFile(dmResource::HFactory factory, const char* path)

Removes a previously registered file from the resource system

PARAMETERS

dmResource::HFactory factory Factory handle
const char* path The path of the resource

RETURNS

dmResource::Result 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


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


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

ResourceTypeCreatorDescBufferSize

void ResourceTypeCreatorDescBufferSize()

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

PARAMETERS


SetupType

void SetupType()

Setup function pointers and context for a resource type

PARAMETERS


Types

FDecryptResource

Decrypts a file


FResourceDecrypt

Encrypts a resource in-place


HDescriptor

Holds information about a currently loaded resource.


HFactory

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


HPreloadHintInfo

Holds information about preloading resources


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

Result

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.

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(HResourceTypeRegisterContext 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(ResourceTypeRegisterContext& ctx)
{
    MyContext** context = (MyContext*)ResourceTypeGetContext(type);
    delete *context;
}

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