This documents an old version of bs::framework. Click here to see the latest release.
Resources

Description

Core resource types and resource management functionality (loading, saving, etc.).

Classes

class  PixelData
 A buffer describing a volume (3D), image (2D) or line (1D) of pixels in memory. More...
 
struct  SpriteSheetGridAnimation
 Descriptor that describes a simple sprite sheet animation. More...
 
class  SpriteTexture
 Texture that references a part of a larger texture by specifying an UV subset. More...
 
struct  TEXTURE_DESC
 Descriptor structure used for initialization of a Texture. More...
 
struct  TEXTURE_COPY_DESC
 Structure used for specifying information about a texture copy operation. More...
 
class  TextureProperties
 Properties of a Texture. More...
 
class  Texture
 Abstract class representing a texture. More...
 
class  ShaderInclude
 Raw text resource that serves as an include file for shaders. More...
 
struct  MESH_DESC
 Descriptor object used for creation of a new Mesh object. More...
 
class  Mesh
 Primary class for holding geometry. More...
 
class  MeshProperties
 Properties of a Mesh. More...
 
class  VertexElemIter< T >
 Iterator that allows you to easily populate or read vertex elements in MeshData. More...
 
struct  BoneWeight
 Contains per-vertex bone weights and indexes used for skinning, for up to four bones. More...
 
class  MeshData
 Contains mesh vertex and index data used for initializing, updating and reading mesh data from Mesh. More...
 
class  MeshHeap
 Mesh heap allows you to quickly allocate and deallocate a large amounts of temporary meshes without the large overhead of normal Mesh creation. More...
 
class  TransientMesh
 Represents a single mesh entry in the MeshHeap. More...
 
class  VertexDataDesc
 Contains information about layout of vertices in a buffer. More...
 
class  Resource
 Base class for all resources. More...
 
class  ResourceMetaData
 Class containing meta-information describing a resource. More...
 
class  Resources
 Manager for dealing with all engine resources. More...
 

Typedefs

typedef ResourceHandle< ResourceHResource
 
typedef ResourceHandle< TextureHTexture
 
typedef ResourceHandle< MeshHMesh
 
typedef ResourceHandle< MaterialHMaterial
 
typedef ResourceHandle< ShaderIncludeHShaderInclude
 
typedef ResourceHandle< FontHFont
 
typedef ResourceHandle< ShaderHShader
 
typedef ResourceHandle< PrefabHPrefab
 
typedef ResourceHandle< StringTableHStringTable
 
typedef ResourceHandle< PhysicsMaterialHPhysicsMaterial
 
typedef ResourceHandle< PhysicsMeshHPhysicsMesh
 
typedef ResourceHandle< AudioClipHAudioClip
 
typedef ResourceHandle< AnimationClipHAnimationClip
 
typedef ResourceHandle< SpriteTextureHSpriteTexture
 
typedef ResourceHandle< VectorFieldHVectorField
 
template<typename T >
using ResourceHandle = TResourceHandle< T, false >
 Represents a handle to a resource. More...
 
template<typename T >
using WeakResourceHandle = TResourceHandle< T, true >
 Represents a handle to a resource. More...
 
typedef Flags< ResourceLoadFlagResourceLoadFlags
 

Enumerations

enum  PixelFormat {
  PF_UNKNOWN = 0, PF_R8 = 1, PF_RG8 = 2, PF_RGB8 = 3,
  PF_BGR8 = 4, PF_BGRA8 = 7, PF_RGBA8 = 8, PF_BC1 = 13,
  PF_BC1a = 14, PF_BC2 = 15, PF_BC3 = 16, PF_BC4 = 17,
  PF_BC5 = 18, PF_BC6H = 19, PF_BC7 = 20, PF_R16F = 21,
  PF_RG16F = 22, PF_RGBA16F = 24, PF_R32F = 25, PF_RG32F = 26,
  PF_RGB32F = 27, PF_RGBA32F = 28, PF_D32_S8X24 = 29, PF_D24S8 = 30,
  PF_D32 = 31, PF_D16 = 32, PF_RG11B10F = 33, PF_RGB10A2 = 34,
  PF_R8I = 35, PF_RG8I = 36, PF_RGBA8I = 37, PF_R8U = 38,
  PF_RG8U = 39, PF_RGBA8U = 40, PF_R8S = 41, PF_RG8S = 42,
  PF_RGBA8S = 43, PF_R16I = 44, PF_RG16I = 45, PF_RGBA16I = 46,
  PF_R16U = 47, PF_RG16U = 48, PF_RGBA16U = 49, PF_R32I = 50,
  PF_RG32I = 51, PF_RGB32I = 52, PF_RGBA32I = 53, PF_R32U = 54,
  PF_RG32U = 55, PF_RGB32U = 56, PF_RGBA32U = 57, PF_R16S = 58,
  PF_RG16S = 59, PF_RGBA16S = 60, PF_R16 = 61, PF_RG16 = 62,
  PF_RGB16 = 63, PF_RGBA16 = 64, PF_COUNT
}
 Pixel formats usable by images, textures and render surfaces. More...
 
enum  PixelFormatFlags {
  PFF_HASALPHA = 0x1, PFF_COMPRESSED = 0x2, PFF_FLOAT = 0x4, PFF_DEPTH = 0x8,
  PFF_INTEGER = 0x10, PFF_SIGNED = 0x20, PFF_NORMALIZED = 0x40
}
 Flags defining some properties of pixel formats. More...
 
enum  PixelComponentType {
  PCT_BYTE = 0, PCT_SHORT = 1, PCT_INT = 2, PCT_FLOAT16 = 3,
  PCT_FLOAT32 = 4, PCT_PACKED_R11G11B10 = 5, PCT_PACKED_R10G10B10A2 = 6, PCT_COUNT
}
 Types used for individual components of a pixel. More...
 
enum  TextureFilter { TF_NEAREST, TF_BILINEAR }
 Determines how are texture pixels filtered during sampling. More...
 
enum  CubemapFace {
  CF_PositiveX, CF_NegativeX, CF_PositiveY, CF_NegativeY,
  CF_PositiveZ, CF_NegativeZ
}
 A list of cubemap faces. More...
 
enum  SpriteAnimationPlayback { None, Normal, Loop, PingPong }
 Type of playback to use for an animation of a SpriteTexture. More...
 
enum  TextureUsage {
  TU_STATIC = GBU_STATIC, TU_DYNAMIC = GBU_DYNAMIC, TU_RENDERTARGET = 0x200, TU_DEPTHSTENCIL = 0x400,
  TU_LOADSTORE = 0x800, TU_CPUCACHED = 0x1000, TU_CPUREADABLE = 0x2000, TU_DEFAULT = TU_STATIC
}
 Flags that describe how is a texture used. More...
 
enum  TextureMipmap { MIP_UNLIMITED = 0x7FFFFFFF }
 Texture mipmap options. More...
 
enum  MeshUsage { MU_STATIC = 1 << 0, MU_DYNAMIC = 1 << 1, MU_CPUCACHED = 0x1000 }
 Planned usage for the mesh. More...
 
enum  ResourceLoadFlag {
  None = 0, LoadDependencies = 1 << 0, KeepInternalRef = 1 << 1, KeepSourceData = 1 << 2,
  Default = LoadDependencies | KeepInternalRef
}
 Flags that can be used to control resource loading. More...
 

Functions

template<class _Ty1 , class _Ty2 , bool Weak>
TResourceHandle< _Ty1, Weak > static_resource_cast (const TResourceHandle< _Ty2, Weak > &other)
 Casts one resource handle to another. More...
 
 BS_FLAGS_OPERATORS (ResourceLoadFlag)
 
BS_CORE_EXPORT ResourcesgResources ()
 Provides easier access to Resources manager. More...
 

Typedef Documentation

◆ ResourceHandle

using ResourceHandle = TResourceHandle<T, false>

Represents a handle to a resource.

Handles are similar to a smart pointers, but they have two advantages:

  • When loading a resource asynchronously you can be immediately returned the handle that you may use throughout the engine. The handle will be made valid as soon as the resource is loaded.
  • Handles can be serialized and deserialized, therefore saving/restoring references to their original resource.

◆ WeakResourceHandle

Represents a handle to a resource.

Handles are similar to a smart pointers, but they have two advantages:

  • When loading a resource asynchronously you can be immediately returned the handle that you may use throughout the engine. The handle will be made valid as soon as the resource is loaded.
  • Handles can be serialized and deserialized, therefore saving/restoring references to their original resource.

Weak handles don't prevent the resource from being unloaded.

Enumeration Type Documentation

◆ CubemapFace

A list of cubemap faces.

◆ MeshUsage

enum MeshUsage

Planned usage for the mesh.

These options usually affect performance and you should specify static if you don't plan on modifying the mesh often, otherwise specify dynamic.

Enumerator
MU_STATIC 

Specify for a mesh that is not often updated from the CPU.

MU_DYNAMIC 

Specify for a mesh that is often updated from the CPU.

MU_CPUCACHED 

All mesh data will also be cached in CPU memory, making it available for fast read access from the CPU.

Can be combined with other usage flags.

◆ PixelComponentType

Types used for individual components of a pixel.

Enumerator
PCT_BYTE 

8-bit integer per component

PCT_SHORT 

16-bit integer per component.

PCT_INT 

32-bit integer per component.

PCT_FLOAT16 

16 bit float per component

PCT_FLOAT32 

32 bit float per component

PCT_PACKED_R11G11B10 

11 bits for first two components, 10 for third component.

PCT_PACKED_R10G10B10A2 

10 bits for first three components, 2 bits for last component

PCT_COUNT 

Number of pixel types.

◆ PixelFormat

Pixel formats usable by images, textures and render surfaces.

Enumerator
PF_UNKNOWN 

Unknown pixel format.

PF_R8 

8-bit 1-channel pixel format, unsigned normalized.

PF_RG8 

8-bit 2-channel pixel format, unsigned normalized.

PF_RGB8 

8-bit 3-channel pixel format, unsigned normalized.

PF_BGR8 

8-bit 3-channel pixel format, unsigned normalized.

PF_BGRA8 

8-bit 4-channel pixel format, unsigned normalized.

PF_RGBA8 

8-bit 4-channel pixel format, unsigned normalized.

PF_BC1 

DXT1/BC1 format containing opaque RGB or 1-bit alpha RGB.

4 bits per pixel.

PF_BC1a 

DXT3/BC2 format containing RGB with premultiplied alpha.

4 bits per pixel.

PF_BC2 

DXT3/BC2 format containing RGB with explicit alpha.

8 bits per pixel.

PF_BC3 

DXT5/BC2 format containing RGB with explicit alpha.

8 bits per pixel. Better alpha gradients than BC2.

PF_BC4 

One channel compressed format.

4 bits per pixel.

PF_BC5 

Two channel compressed format.

8 bits per pixel.

PF_BC6H 

Format storing RGB in half (16-bit) floating point format usable for HDR.

8 bits per pixel.

PF_BC7 

Format storing RGB with optional alpha channel.

Similar to BC1/BC2/BC3 formats but with higher quality and higher decompress overhead. 8 bits per pixel.

PF_R16F 

16-bit 1-channel pixel format, signed float.

PF_RG16F 

16-bit 2-channel pixel format, signed float.

PF_RGBA16F 

16-bit 4-channel pixel format, signed float.

PF_R32F 

32-bit 1-channel pixel format, signed float.

PF_RG32F 

32-bit 2-channel pixel format, signed float.

PF_RGB32F 

32-bit 3-channel pixel format, signed float.

PF_RGBA32F 

32-bit 4-channel pixel format, signed float.

PF_D32_S8X24 

Depth stencil format, 32bit depth, 8bit stencil + 24 unused.

Depth stored as signed float.

PF_D24S8 

Depth stencil fomrat, 24bit depth + 8bit stencil.

Depth stored as unsigned normalized.

PF_D32 

Depth format, 32bits.

Signed float.

PF_D16 

Depth format, 16bits.

Unsigned normalized.

PF_RG11B10F 

Packed unsigned float format, 11 bits for red, 11 bits for green, 10 bits for blue.

PF_RGB10A2 

Packed unsigned normalized format, 10 bits for red, 10 bits for green, 10 bits for blue, and two bits for alpha.

PF_R8I 

8-bit 1-channel pixel format, signed integer.

PF_RG8I 

8-bit 2-channel pixel format, signed integer.

PF_RGBA8I 

8-bit 4-channel pixel format, signed integer.

PF_R8U 

8-bit 1-channel pixel format, unsigned integer.

PF_RG8U 

8-bit 2-channel pixel format, unsigned integer.

PF_RGBA8U 

8-bit 4-channel pixel format, unsigned integer.

PF_R8S 

8-bit 1-channel pixel format, signed normalized.

PF_RG8S 

8-bit 2-channel pixel format, signed normalized.

PF_RGBA8S 

8-bit 4-channel pixel format, signed normalized.

PF_R16I 

16-bit 1-channel pixel format, signed integer.

PF_RG16I 

16-bit 2-channel pixel format, signed integer.

PF_RGBA16I 

16-bit 4-channel pixel format, signed integer.

PF_R16U 

16-bit 1-channel pixel format, unsigned integer.

PF_RG16U 

16-bit 2-channel pixel format, unsigned integer.

PF_RGBA16U 

16-bit 4-channel pixel format, unsigned integer.

PF_R32I 

32-bit 1-channel pixel format, signed integer.

PF_RG32I 

32-bit 2-channel pixel format, signed integer.

PF_RGB32I 

32-bit 3-channel pixel format, signed integer.

PF_RGBA32I 

32-bit 4-channel pixel format, signed integer.

PF_R32U 

32-bit 1-channel pixel format, unsigned integer.

PF_RG32U 

32-bit 2-channel pixel format, unsigned integer.

PF_RGB32U 

32-bit 3-channel pixel format, unsigned integer.

PF_RGBA32U 

32-bit 4-channel pixel format, unsigned integer.

PF_R16S 

16-bit 1-channel pixel format, signed normalized.

PF_RG16S 

16-bit 2-channel pixel format, signed normalized.

PF_RGBA16S 

16-bit 4-channel pixel format, signed normalized.

PF_R16 

16-bit 1-channel pixel format, unsigned normalized.

PF_RG16 

16-bit 2-channel pixel format, unsigned normalized.

PF_RGB16 

16-bit 3-channel pixel format, unsigned normalized.

PF_RGBA16 

16-bit 4-channel pixel format, unsigned normalized.

PF_COUNT 

Number of pixel formats currently defined.

◆ PixelFormatFlags

Flags defining some properties of pixel formats.

Enumerator
PFF_HASALPHA 

This format has an alpha channel.

PFF_COMPRESSED 

This format is compressed.

This invalidates the values in elemBytes, elemBits and the bit counts as these might not be fixed in a compressed format.

PFF_FLOAT 

This is a floating point format.

PFF_DEPTH 

This is a depth format (for depth textures).

PFF_INTEGER 

This format stores data internally as integers.

PFF_SIGNED 

Format contains signed data.

Absence of this flag implies unsigned data.

PFF_NORMALIZED 

Format contains normalized data.

This will be [0, 1] for unsigned, and [-1,1] for signed formats.

◆ ResourceLoadFlag

enum ResourceLoadFlag
strong

Flags that can be used to control resource loading.

Enumerator
None 

No flags.

LoadDependencies 

If enabled all resources referenced by the root resource will be loaded as well.

KeepInternalRef 

If enabled the resource system will keep an internal reference to the resource so it doesn't get destroyed when it goes out of scope.

You can call Resources::release() to release the internal reference. Each call to load will create a new internal reference and therefore must be followed by the same number of release calls. If dependencies are being loaded, they will not have internal references created regardless of this parameter.

KeepSourceData 

Determines if the loaded resource keeps original data loaded.

Sometime resources will process loaded data and discard the original (e.g. uncompressing audio on load). This flag can prevent the resource from discarding the original data. The original data might be required for saving the resource (via Resources::save), but will use up extra memory. Normally you want to keep this enabled if you plan on saving the resource to disk.

Default 

Default set of flags used for resource loading.

◆ SpriteAnimationPlayback

Type of playback to use for an animation of a SpriteTexture.

Enumerator
None 

Do not animate.

Normal 

Animate once until the end of the animation is reached.

Loop 

Animate to the end of the animation then loop around.

PingPong 

Loop the animation but reverse playback when the end is reached.

◆ TextureFilter

Determines how are texture pixels filtered during sampling.

Enumerator
TF_NEAREST 

Pixel nearest to the sampled location is chosen.

TF_BILINEAR 

Four pixels nearest to the sampled location are interpolated to yield the sampled color.

◆ TextureMipmap

Texture mipmap options.

Enumerator
MIP_UNLIMITED 

Create all mip maps down to 1x1.

◆ TextureUsage

Flags that describe how is a texture used.

Enumerator
TU_STATIC 

A regular texture that is not often or ever updated from the CPU.

TU_DYNAMIC 

A regular texture that is often updated by the CPU.

TU_RENDERTARGET 

Texture that can be rendered to by the GPU.

TU_DEPTHSTENCIL 

Texture used as a depth/stencil buffer by the GPU.

TU_LOADSTORE 

Texture that allows load/store operations from the GPU program.

TU_CPUCACHED 

All mesh data will also be cached in CPU memory, making it available for fast read access from the CPU.

TU_CPUREADABLE 

Allows the CPU to directly read the texture data buffers from the GPU.

TU_DEFAULT 

Default (most common) texture usage.

Function Documentation

◆ gResources()

BS_CORE_EXPORT Resources& bs::gResources ( )

Provides easier access to Resources manager.

◆ static_resource_cast()

TResourceHandle<_Ty1, Weak> bs::static_resource_cast ( const TResourceHandle< _Ty2, Weak > &  other)

Casts one resource handle to another.