Resources and assets are an important part of the engine. Handling the creation, loading, rendering and lifetime management is left to different parts of the system.
The available types of resources are:
All types of resources are handled by individual resource managers derived from Cogs::Core::ResourceManager, which provide APIs for creation and processing. The creation APIs are what is commonly used by developers creating features, while the processing APIs are run by the Engine and core systems. The resource managers can be accessed through the Context object.
There are primarily two ways of creating resources, manually, and loading from resource-specific load info structures providing the resource managers with enough information to create and populate the resource with data.
Typical manual resource creation looks as follows:
...
// Global context.
Context * context;
// From some entity.
MeshComponent * meshComponent;
{
// Create a new resource, store the handle in a local variable.
// the resource is guaranteed to exist as long as the handle.
auto meshHandle = context->meshManager->create();
// Access the resource itself by letting the resource manager resolve
// the resource for us.
auto mesh = context->meshManager->get(meshHandle);
// Set some data
mesh->setVertexData(...);
mesh->setIndexData(...);
// Hand the mesh over to a MeshRenderComponent which will then render it.
// The mesh resource is now guaranteed to be alive as long as the
// MeshComponent instance or our local meshHandle variable are alive.
meshComponent->meshHandle = meshHandle;
// As we leave the local scope meshHandle will decrement the reference count
// of the reference, but meshComponent->meshHandle will still keep it alive.
}
...
In this instance, the Cogs::Core::Mesh::setVertexData() and other calls to the Mesh resource will set its state to Cogs::Core::ResourceState::Changed. This will in turn place the resource in a internal queue with the resource manager, pending handing the resource over to the renderer at a later stage. The resource can then be transferred to the GPU (as in the case of meshes and textures), or otherwise handled.
Using the Cogs.Native interface:
// Global context.
BridgeContext * context;
{
auto entity = new Cogs::Native::MeshPart(context, "Mesh");
Cogs::Native::Mesh meshId(context, ::loadMesh(context));
std::vector positions = ...;
std::vector attributes(positions.size());
meshId.setPositions(positions);
meshId.setColors(attributes);
meshId.setPrimitiveType(::PrimitiveType::TriangleList);
entity->meshComponent->meshHandle = meshId;
}
Loading a resource from a load info structure typically looks as follows:
...
// Global context.
Context * context;
// From some entity.
MaterialComponent * materialComponent;
{
// Create a load info. These are specific to the kind of resource being loaded.
TextureLoadInfo textureLoad;
// Load from a file.
textureLoad.resourcePath = "./Textures/Texture.png";
textureLoad.resourceName = "MyTexture";
// We must create a resource to load the data into.
textureLoad.handle = context->textureManager->create();
// Hand the load info over to the texture manager to load and populate the
// texture resource from the file given.
auto textureHandle = context->textureManager->loadResource(loadInfo);
// Use the texture as diffuse map
materialComponent->diffuseMap = textureHandle;
}
...
Using the Cogs.Native interface:
...
// Global context.
BridgeContext * context;
// From some entity.
Cogs::Native::MaterialComponent * materialComponent;
{
ResourceId textureHandle = ::getNextTextureId(context);
::loadTexture(context, textureHandle, "./Textures/Texture.png", static_cast(Cogs::Native::TextureLoadFlags::None));
// Use the texture as diffuse map
materialComponent->diffuseMap = { textureHandle };
}
...
After the call to loadResource() the load info structure will be placed in an internal queue, waiting to be loaded. When the processLoading() phase is entered resource managers will look for a suitable loader (implementing Cogs::Core::IResourceLoader specialized for the type of load info) to handle the information in the load info struct, and hand over loading.
After loading has finished, if successful, the resource is placed in the queue ready for activation, along with manually created and modified resources.
Meshes hold data to render geometric shapes. The data consists of vertex data (positions, texture coordinates, normals etc.), optional index data and a description of how to interpret the data.
The vertex data can consist of multiple streams, with different vertex formats for every stream.
All existing vertex data can be mapped, allowing for reuse of the existing allocations for vertex data memory.
See Mesh for more details.
Textures hold raster data used in combination with effects, material properties and geometry to control the appearance of shapes.
Textures can be loaded from common image file formats like JPEG and PNG (See File Formats for more details) or from data in code.
The texture data can be images, procedurally generated colors, lookup tables, cube maps or similar.
The main types of textures should be handled differently:
Images: To display good looking images the texture should be MipMapped and Texture Addressing modes should normally be 'Clamp'. The default 'Wrap' mode give artifacts at the border (interpolating between last and first pixel).Lookup Tables: Lookup table textures are used in Cogs AssetComponent to map merged geometry meshes back to individual geometry elements. These textures should be set up to display exact original values.
Any mip-mapping and interpolation will pass interpolated values to shaders. A custom shader programmed to highlight a specific Asset Texture ID will fail.[TextureLoadFlags](@ref Cogs::Core::TextureLoadFlags)
Flip - Flip the texture data vertically before it is passed to the rendering backend.ForceSynchronous - Should seldom be used. Leave loading in the background. Note creating a texture by async loading and setting the texture on a material will update the material to an empty texture while loading. Switching image will cause flashing. Delaying material change until texture is loaded recommended.ForceUnique - Do not re-use existing texture. Can be used if showing same path with different settings.LinearColorSpace - If set - Texture is defined in linear colorspace. Set for lookup tables. See definition for more info.NoMipMaps - Do not generate mipmaps. Useful for lookup-table textures. See above.setTextureAddressMode(..) - Sets Addressing modes on Material/MaterialInstance to use when sampling textures. See AddressMode
setTextureFilterMode(..) - Sets filter-mode on Material/MaterialInstance used for the texture property. See FilterMode
The current picking in Cogs is CPU based picking. For Meshes picking code will use the texture coordinate of the first vertex in the triangle.
The Cogs Texture resource handling class Texture may give more details.
Effects hold combinations of shaders to apply to the graphics pipeline during rendering. Effects are used by Materials to define how the material is processed during rendering.
See Effect for more details.
Fonts hold data on how to render text to the screen. A font typically consists of a font name (to load from the system), and additional controlling properties such as the font weight and size.
See Font for more details.
While meshes and textures define what data we use while rendering, materials define how we render it. A material consists of an effect and a set of properties to control the behavior of the effect and how the renderer interprets the mesh and texture data.
Material resources are considered templates for material instances.
See Material for more details.
Material instances are created from a material and a set of values for all properties defined by the material. This makes it possible to both share material instances when shapes are supposed to look the same, and use unique instances of the same material when only varying of some properties (for example diffuse color) is needed.
Material instances do not define any additional properties over the material they are created from.
If using a Material Instance created entities should not contain MaterialComponent. Either choose entity without MaterialComponent or remove it.
See MaterialInstance for more details.
Models describe a set of one or more entities, how they are connected together, and the set of resources used to populate the entities with data.
Models do not by themselves define any data structures that are used during rendering, but are instead instanced by the ModelSystem into sets of entities using shared resources for the model instance.
See Model for more details.