Tramway SDK 0.0.9
Github
Quick links
Home
Get Started
Resources
A resource is any kind of thing that you want to you want to be streamed in from the disk or any other location.
Resources can be loaded directly, or they can be passed to the Async system to be streamed in.
Some resource types included in the framework are Models, Materials and Sounds.
Key concepts
Name
Each resource has a unique name. This is how resources are identified. Usually the name references the name of a file on disk, but does not always have to be so.
The uniqueness only applies to resources of the same type. Different types of resources can have a resource with the same name.
References
This is how the framework keeps track of which resources are being used and which resources can be freed. Used resources are not freed.
Whenever an EntityComponent or any other user starts using a resource, they should add a reference to the resource, in order to mark it as being used. After the usage of the resource ceases, the reference should be removed.
If you want a resource to be always availabe, you can add a reference to it. This way it will never be freed and you won't have to wait for it to be streamed in.
Status
The status of the resource keeps track of whether the resource needs to be loaded or whether it is ready for usage.
Statuses
Unloaded | UNLOADED
The resource has not been loaded from disk.
Loaded | LOADED
The resource has been loaded form disk, but needs further processing. For example, graphics resources use this status for when they have been parsed from the disk, but haven't been uploaded to the GPU memory, since this step has to happen on the main thread, not the resource streaming thread.
Ready | READY
The resource has been fully loaded and is ready for use.
Load fail
While not implemented as a status (it was at one point, but the API was not that neat to use), the load fail is flag that keeps track of whether the resource was successfully loaded.
For example, the resource could be considered as having failed to load if the file associated with the resource was missing, or if it the format of the file was determined to be invalid.
Programming in C++
#include <framework/resource.h>
API documentation
page.
If you want to use a resource, you can use the ResourceProxy class. It is a type of smart pointer, which will not only automatically keep track of references, but also automatically pass the resource to the Aync system for streaming, if the resource is not loaded already.
ResourceProxy<Material> material;
material.set(Material::Find("mongus"));
// if the mongus material hasn't been loaded yet,
// it will now have been added to the Async
// resource streaming queue
if (material->GetStatus() == Resource::READY) {
printf("width: %f height: %f\n",
material->GetWidth(),
material->GetHeight());
}
To create a resource, you will need to create a subclass of the Resource class.
class NewResource : public Resource {
public:
NewResource(name_t name) {
Resource::Resource(name);
}
void LoadFromDisk();
void LoadFromMemory();
void Unload();
private:
int* data;
};
After that, you will need to implement the resource loading methods, as well as a resource cleanup method.
void NewResource::LoadFromDisk() {
this->data = data_from_disk;
if (this->data == bad_data) {
this->load_fail = true;
this->data = dummy_data;
}
if (requires_further_processing) {
this->status = LOADED;
} else {
this->status = READY;
}
}
void NewResource::LoadFromMemory() {
main_thread_processing(this->data);
this->status = READY;
}
void NewResource::Unload() {
yeet_data(this->data);
}
If the resource can't be located from the disk, you should generate some dummy data and check the load_fail flag. For example, if the Material resource can't load the texture image associated with that material, it will generate a checkerboard pattern texture image.
