nResource Class Reference
[Resource System]
#include <nresource.h>
Inheritance diagram for nResource:
Detailed Description
Super class for all resource classes. Resources are mostly loaded from a file, can be shared, and unloaded to free runtime space. They are managed by a central resource server.The nResource class provides an interface for asynchronous loading (loading resources in a background thread). Not all subclasses may support asynchronous resource loading though.
Default behavior is synchronous loading (Load() returns when the resource has been loaded). Asynchronous loading is enabled by calling SetAsyncEnabled(true). When async loading is enabled, Load() returns immediately with a return value of true but IsValid() will return false until the resource has actually been loaded at some point in the future.
To check whether a resource loading request has been issued at some point in the past which has not been fullfilled yet, call the IsPending() method. IsPending() returns true after an async call to Load() and before IsValid() returns true to indicate the the resource is available. In all other cases, IsPending() returns false.
Unloading resources always happened immediately, both in sync and async mode.
A resource object can be in one of the following states:
- Unloaded: The resource is not currently loaded, resource object are in this state before Load() and after Unload()
- Valid: The resource object has been loaded and is in a valid state to be used.
- Lost: The resource has been loaded at some time in the past, but is currently in a Lost state, so that it can't be used. This can happen for D3D-controlled resources which are not placed in D3D's managed resource pool. Usually, applications don't need to be concerned about lost state, since no rendering will be performend while the application is in a lost state.
- Empty: The resource has been initialized, but has not been filled with valid data. This is usually only of interest for special types of resources which are not loaded from disk resource files, but are filled by application code with data. This includes for instance procedurally generated meshes and textures. In general, only resources which are not provided with a filename can enter the Empty state. The code which uses the resources must check the resource for Empty state each frame before using the resource, and if the resource is in Empty state, initialize the contents of the resource, and set the resource to Valid state.
Only resources which cannot initializes themselves from a file can go into Empty state, for those resources, Empty state will be entered after initializing the resource by calling Load(), or for resources which can go into Lost state, if a full-screen application loses focus (for instance through Alt-TAB).
Resources which don't know how to load themselves may remain in Unloaded state after the display has been closed and opened (this happens for instance on Alt-RETURN).
For the general case (meshes and textures which load themselves from files), all resource management happens automatically. Special cases (where resources are not loaded from normal resource files) should check for Empty or Unloaded state before using the resources, and initialize, or load the resources manually (don't forget to set the resource to Valid state afterwards).
This should only be of concern for programmers which extend Nebula2 itself. Client applications should NEVER have to deal with any type of low level resource management.
Also check out the nResourceLoader class, this is a very clean way to handle custom initialization of resources without having to check manually for an invalid state. If a resource loader is attached to a resource object, it will be responsible for loading and unloading the resource. Subsystems which do their own resource management may derive subclasses from nResourceLoader.
(C) 2002 RadonLabs GmbH
Definition at line 97 of file nresource.h.
Public Types | |
| enum | Type { Bundle = (1<<0), Mesh = (1<<1), Texture = (1<<2), Shader = (1<<3), Animation = (1<<4), SoundResource = (1<<5), SoundInstance = (1<<6), Font = (1<<7), Database = (1<<8), Other = (1<<9), AllResourceTypes = (Bundle | Mesh | Texture | Shader | Animation | SoundResource | SoundInstance | Font | Database | Other), InvalidResourceType = (1<<30) } |
| general resource types More... | |
| enum | State { Unloaded, Valid, Lost, Empty } |
| resource states More... | |
Public Member Functions | |
| nResource () | |
| constructor | |
| virtual | ~nResource () |
| destructor | |
| virtual bool | CanLoadAsync () const |
| subclasses must indicate to nResource whether async mode is supported | |
| void | SetType (Type t) |
| set resource type | |
| Type | GetType () const |
| get resource type | |
| void | SetFilename (const nString &path) |
| set absolute path to resource file | |
| nString | GetFilename () |
| get absolute filename to resource file | |
| void | SetAsyncEnabled (bool b) |
| enable/disable async behavior | |
| bool | GetAsyncEnabled () const |
| get async behavior | |
| void | SetResourceLoader (const nString &resourceLoader) |
| set the NOH path to an nResourceLoader | |
| const char * | GetResourceLoader () |
| gets the NOH path to the nResourceLoader | |
| bool | IsPending () const |
| is a resource loading request pending? | |
| virtual bool | Load () |
| issue a load request | |
| virtual bool | Load (nFile *file, int offset, int length) |
| issue a load request from an open file, FIXME: this kinda sucks, Floh. | |
| virtual void | Unload () |
| unloads the resource | |
| void | SetState (State s) |
| set the valid flag | |
| State | GetState () const |
| get current state, this can be Lost, Restored, Valid | |
| bool | IsValid () const |
| convenience method, returns true when GetState() == Valid | |
| bool | IsUnloaded () const |
| convenience method, returns true when GetState() == Unloaded | |
| bool | IsLoaded () const |
| convenience method, returns GetState() != Unloaded | |
| bool | IsLost () const |
| convenience method, returns true when GetState() == Lost | |
| bool | IsEmpty () const |
| convenience method, returns true when GetState() == Empty | |
| virtual int | GetByteSize () |
| get an estimated byte size of the resource data (for memory statistics) | |
| uint | GetUniqueId () const |
| get the unique id of this resource | |
Protected Member Functions | |
| virtual bool | LoadResource () |
| override in subclass to perform actual resource loading | |
| virtual void | UnloadResource () |
| override in subclass to perform actual resource unloading | |
| virtual void | OnLost () |
| called when contained resource may become lost | |
| virtual void | OnRestored () |
| called when contained resource may be restored | |
Protected Attributes | |
| nDynAutoRef< nResourceLoader > | refResourceLoader |
Friends | |
| class | nResourceServer |
Member Enumeration Documentation
|
|
general resource types
Reimplemented in nTexture2, and nShadowCaster2. Definition at line 101 of file nresource.h. |
|
|
resource states
Definition at line 119 of file nresource.h. |
Constructor & Destructor Documentation
|
|
constructor
Definition at line 17 of file nresource_main.cc. |
|
|
destructor
Definition at line 30 of file nresource_main.cc. |
Member Function Documentation
|
|
subclasses must indicate to nResource whether async mode is supported Subclasses must override this method to indicate to the nResource class whether they support asynchronous resource loading. Default is false. Reimplemented in nD3D9Mesh, nD3D9Texture, nCLODMesh, nCLODSplat, nCLODTile, nChunkLodMesh, nGLMesh, and nGLTexture. Definition at line 72 of file nresource_main.cc. |
|
|
set resource type Set the resource type.
Reimplemented in nTexture2. Definition at line 210 of file nresource.h. |
|
|
get resource type Get the resource type.
Reimplemented in nTexture2. Definition at line 223 of file nresource.h. |
|
|
set absolute path to resource file Set the absolute path(!) to the resource file. The path can contain Nebula-Assigns.
Definition at line 237 of file nresource.h. |
|
|
get absolute filename to resource file Get the absolute path to the resource file. Returns a copy of the string, because in asynchronous mode it is not guaranteed that a string reference will remain valid.
Definition at line 254 of file nresource.h. |
|
|
enable/disable async behavior Enable/disable asynchronous behavior.
Definition at line 270 of file nresource.h. |
|
|
get async behavior Get the async behavior flag.
Definition at line 283 of file nresource.h. |
|
|
set the NOH path to an nResourceLoader Sets a resource loader for the nResource
Definition at line 49 of file nresource_main.cc. |
|
|
gets the NOH path to the nResourceLoader Gets the currently-set resource loader
Definition at line 61 of file nresource_main.cc. |
|
|
is a resource loading request pending? Return whether a yet-unfullfilled resource loading request is pending.
Definition at line 372 of file nresource.h. |
|
|
issue a load request Request to load a resource in synchronous or asynchronous mode. Will care about multithreading issues and invoke the LoadResource() method which should be overriden by subclasses to implement the actual loading. Subclasses must indicate with the CanLoadAsync() method whether they support asynchronous loading or not. NOTE: in asynchronous mode, the method will return true although the resource data is not available yet. Use the IsValid() method to check when the resource data is available.
Reimplemented in nStreamingAnimation, and nCLODTile. Definition at line 92 of file nresource_main.cc. |
|
||||||||||||||||
|
issue a load request from an open file, FIXME: this kinda sucks, Floh. Loads the resource from within an open file. This method should be overridden by subclasses.
Reimplemented in nCLODMesh, and nCLODSplat. Definition at line 126 of file nresource_main.cc. |
|
|
unloads the resource Unload the resource data, freeing runtime resources. This method will call the protected virtual UnloadResources() method which should be overriden by subclasses. This method works in sync and async mode and care about the multi-threading issues before and after calling LoadResources(); Reimplemented in nStreamingAnimation, nCLODMesh, and nCLODSplat. Definition at line 141 of file nresource_main.cc. |
|
|
set the valid flag Set the current state, this can be Unloaded, Lost, Restored, Valid.
Definition at line 296 of file nresource.h. |
|
|
get current state, this can be Lost, Restored, Valid Return the current state.
Definition at line 309 of file nresource.h. |
|
|
convenience method, returns true when GetState() == Valid
Definition at line 319 of file nresource.h. |
|
|
convenience method, returns true when GetState() == Unloaded
Definition at line 329 of file nresource.h. |
|
|
convenience method, returns GetState() != Unloaded
Definition at line 339 of file nresource.h. |
|
|
convenience method, returns true when GetState() == Lost
Definition at line 359 of file nresource.h. |
|
|
convenience method, returns true when GetState() == Empty
Definition at line 349 of file nresource.h. |
|
|
get an estimated byte size of the resource data (for memory statistics) Return an estimated byte size of the resource data. This is only used for statistics. Reimplemented in nMemoryAnimation, nD3D9Mesh, nD3D9Texture, nInstanceStream, nMesh2, nGLMesh, and nGLTexture. Definition at line 214 of file nresource_main.cc. |
|
|
get the unique id of this resource Returns the unique id of this resource object. You should use the unique id to check whether 2 resources are identical instead of comparing their pointers. Definition at line 385 of file nresource.h. |
|
|
override in subclass to perform actual resource loading Subclasses must override this method and implement the actual resource loading code here. The method may get called from a thread (if the class returns true in the CanLoadAsync() method and the resource object works in async mode). Reimplemented in nMemoryAnimation, nDSound3, nDSoundResource, nD3D9Font, nD3D9Mesh, nD3D9MeshArray, nD3D9Texture, nInstanceStream, nMesh2, nMeshArray, nResourceBundle, nSkinnedShadowCaster2, nStaticShadowCaster2, nSQLite3Database, nCLODMesh, nCLODSplat, nCLODTile, nChunkLodMesh, nChunkLodTree, nOpenALObj, nOpenALResource, nCgFXShader, nGLFont, nGLMesh, and nGLTexture. Definition at line 162 of file nresource_main.cc. |
|
|
override in subclass to perform actual resource unloading Subclasses must override this method and implement the resource unloading. This method will always run in the main thread. Reimplemented in nAnimation, nMemoryAnimation, nDSound3, nDSoundResource, nD3D9Font, nD3D9Mesh, nD3D9MeshArray, nD3D9Texture, nInstanceStream, nMesh2, nMeshArray, nResourceBundle, nSkinnedShadowCaster2, nStaticShadowCaster2, nSQLite3Database, nCLODMesh, nCLODSplat, nCLODTile, nChunkLodMesh, nChunkLodTree, nOpenALObj, nOpenALResource, nCgFXShader, nGLFont, nGLMesh, and nGLTexture. Definition at line 173 of file nresource_main.cc. |
|
|
called when contained resource may become lost This method is called if any unmanaged contained resources may become lost (for instance because the the D3D device goes into lost state). Subclasses which are affected by lost device state should unload their resources and set the resource object's state to Lost. Otherwise they should do nothing (these are usually only classes which placed their resources in D3D's default resource pool. Reimplemented in nD3D9Font, nD3D9Mesh, nD3D9Texture, nGLMesh, and nGLTexture. Definition at line 188 of file nresource_main.cc. |
|
|
called when contained resource may be restored This method is called when unmanaged contained resources should be restored (for instance because the D3D device is available again). Subclasses which were affected by OnLost(), should restore their resource objects, and set the resource's state to Restored, if some external client needs to fill data into the object, or to Valid, if the object could completely be restored. Reimplemented in nD3D9Font, nD3D9Mesh, nD3D9Texture, nGLMesh, and nGLTexture. Definition at line 203 of file nresource_main.cc. |
Friends And Related Function Documentation
|
|
Definition at line 177 of file nresource.h. |
Member Data Documentation
|
|
Definition at line 188 of file nresource.h. |
The documentation for this class was generated from the following files:
