Resource::GetResource

Defined in: C4Resources.h

Returns a pointer to a resource object.

Prototype

static type *GetResource(const char *name, uint32 flags = 0, ResourceCatalog *catalog = nullptr, ResourceLocation *location = nullptr);

Parameters

`name`	The name of the resource, including any containing folder names separated by forward slashes.
`flags`	The resource load flags. See below for possible values.
`catalog`	The resource catalog from which the resource should be loaded.
`location`	If not `nullptr`, then the path to the directory containing the resource is returned here when the resource is loaded from the virtual catalog.

Description

The GetResource function returns a pointer to a resource object of the type corresponding to the template parameter of the Resource class. If the resource object already exists, then its reference count is incremented and a pointer to the existing object is returned. Otherwise, a new resource object is created and the resource data is loaded into memory (unless the kResourceDeferLoad flag is specified). If the resource data does not exist on disk, then the return value is nullptr.

Each successful call to the GetResource function should be balanced by a matching call to the Resource::Release function.

The flags parameter can be a combination (through logical OR) of the following constants.

`kResourceDeferLoad`	The resource data is not loaded when the resource object is constructed.
`kResourceNoDefault`	Do not load a default resource if the requested resource does not exist.
`kResourceUntracked`	This flag is specified to force a new copy of a resource to be loaded from the disk without sharing any copy of the resource that might already be loaded and without going through the resource cache. Pack files are also ignored, so the resource will fail to load if it is not in a separate file.

If the kResourceDeferLoad flag is specified, then the resource data is not loaded, but a resource object is created and returned. Note that in this case, the return value is never nullptr, so it's not possible to determine whether the resource data exists based on the return value. The resource data can subsequently be loaded outside of the resource object using the functions of the ResourceLoader object returned by the Resource::OpenLoader function. The resource data can also be loaded (in its entirety) into the Resource object by calling the Resource::LoadResource function.

If the catalog parameter is nullptr, then the resource is loaded from the virtual catalog.

When a resource is loaded from the virtual catalog and the location parameter is not nullptr, then the path stored in the ResourceLocation object is set to the path to the folder containing the resource file. If the resource was loaded from a pack file, then the path is set to that of the pack file without the extension. The resource location is not set if the kResourceDeferLoad flag is specified in the flags parameter.

Special Considerations

The GetResource function is normally not called directly using the Resource class template. Higher-level classes normally make calls to the GetResource function as part of a larger initialization procedure. The following list names some of those functions and the type of resources that they create.

`WorldMgr::LoadWorld`	World resource.
`Model::GetModel`	Model resource.
`Texture::GetTexture`	Texture resource.
`Sound::LoadSound`	Sound resource.
`Font::GetFont`	Font resource.

Resources indirectly loaded through these functions are released automatically when the higher-level classes that created them are themselves released through the proper calls.