Resource::Get

Defined in: C4Resources.h

Returns a pointer to a resource object.

Prototype

static type *Get(const char *name, unsigned long 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 Get 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 Get function should be balanced by a matching call to the Resource::Release function.

The flags parameter may be 0 or the following value.

`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.
`kResourceIgnorePackFiles`	Ignore pack files when loading the resource.

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::Load 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 Get function is normally not called directly using the Resource class template. Higher-level classes normally make calls to the Get function as part of a larger initialization procedure. The following list names some of those functions and the type of resources that they create.

`Sound::Load`	Sound resource.
`Font::Get`	Font resource.
`Texture::Get`	Texture resource.
`Model::Get`	Model resource.
`WorldMgr::LoadWorld`	World 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.