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

Description

Abstract class representing a texture.

Specific render systems have their own Texture implementations. Internally represented as one or more surfaces with pixels in a certain number of dimensions, backed by a hardware buffer.

Note
Sim thread.

Inherits Resource.

Methods

AsyncOp writeData (const SPtr< PixelData > &data, UINT32 face=0, UINT32 mipLevel=0, bool discardEntireBuffer=false)
 Updates the texture with new data. More...
 
AsyncOp readData (const SPtr< PixelData > &data, UINT32 face=0, UINT32 mipLevel=0)
 Reads internal texture data to the provided previously allocated buffer. More...
 
void readCachedData (PixelData &data, UINT32 face=0, UINT32 mipLevel=0)
 Reads data from the cached system memory texture buffer into the provided buffer. More...
 
const TexturePropertiesgetProperties () const
 Returns properties that contain information about the texture. More...
 
SPtr< ct::TexturegetCore () const
 Retrieves a core implementation of a texture usable only from the core thread. More...
 
RTTITypeBasegetRTTI () const override
 Returns an interface you can use to access class' Run Time Type Information. More...
 
- Methods inherited from Resource
 Resource (bool requiresGpuInitialization=true)
 
const StringgetName () const
 Returns the name of the resource. More...
 
void setName (const String &name)
 Sets the name of the resource. More...
 
SPtr< ResourceMetaDatagetMetaData () const
 Retrieves meta-data containing various information describing a resource. More...
 
virtual bool allowAsyncLoading () const
 Returns whether or not this resource is allowed to be asynchronously loaded. More...
 
RTTITypeBasegetRTTI () const override
 Returns an interface you can use to access class' Run Time Type Information. More...
 
- Methods inherited from IReflectable
bool isDerivedFrom (RTTITypeBase *base)
 Returns true if current RTTI class is derived from base (Or if it is the same type as base). More...
 
UINT32 getTypeId () const
 Returns an unique type identifier of the class. More...
 
const StringgetTypeName () const
 Returns the type name of the class. More...
 
- Methods inherited from CoreObject
virtual void destroy ()
 Frees all the data held by this object. More...
 
bool isInitialized () const
 Returns true if the object has been initialized. More...
 
bool isDestroyed () const
 Returns true if the object has been destroyed. More...
 
void blockUntilCoreInitialized () const
 Blocks the current thread until the resource is fully initialized. More...
 
UINT64 getInternalID () const
 Returns an unique identifier for this object. More...
 
SPtr< CoreObjectgetThisPtr () const
 Returns a shared_ptr version of "this" pointer. More...
 
SPtr< ct::CoreObjectgetCore () const
 Returns an object that contains a core thread specific implementation of this CoreObject. More...
 
void syncToCore ()
 Ensures all dirty syncable data is send to the core thread counterpart of this object (if any). More...
 
void _setThisPtr (SPtr< CoreObject > ptrThis)
 Sets a shared this pointer to this object. More...
 

Static methods

static HTexture create (const TEXTURE_DESC &desc)
 Creates a new empty texture. More...
 
static HTexture create (const SPtr< PixelData > &pixelData, int usage=TU_DEFAULT, bool hwGammaCorrection=false)
 Creates a new 2D or 3D texture initialized using the provided pixel data. More...
 
static RTTITypeBasegetRTTIStatic ()
 
Internal
static SPtr< Texture_createPtr (const TEXTURE_DESC &desc)
 Same as create() excepts it creates a pointer to the texture instead of a texture handle. More...
 
static SPtr< Texture_createPtr (const SPtr< PixelData > &pixelData, int usage=TU_DEFAULT, bool hwGammaCorrection=false)
 Same as create() excepts it creates a pointer to the texture instead of a texture handle. More...
 
- Static methods inherited from Resource
static RTTITypeBasegetRTTIStatic ()
 
- Static methods inherited from IReflectable
static UnorderedMap< UINT32, RTTITypeBase * > & getAllRTTITypes ()
 Returns all available RTTI types. More...
 
static SPtr< IReflectablecreateInstanceFromTypeId (UINT32 rttiTypeId)
 Creates an empty instance of a class from a type identifier. More...
 
static void _registerRTTIType (RTTITypeBase *rttiType)
 Called by each type implementing RTTITypeBase, on program load. More...
 
static RTTITypeBase_getRTTIfromTypeId (UINT32 rttiTypeId)
 Returns class' RTTI type from type id. More...
 
static bool _isTypeIdDuplicate (UINT32 typeId)
 Checks if the provided type id is unique. More...
 
static void _checkForCircularReferences ()
 Iterates over all RTTI types and reports any circular references (for example one type having a field referencing another type, and that type having a field referencing the first type). More...
 
static RTTITypeBasegetRTTIStatic ()
 Returns an interface you can use to access class' Run Time Type Information. More...
 
- Static methods inherited from CoreObject
template<class T , class MemAlloc >
static void _delete (CoreObject *obj)
 Schedules the object to be destroyed, and then deleted. More...
 

Additional Inherited Members

- Protected Types inherited from CoreObject
enum  Flags { CGO_DESTROYED = 0x01, CGO_INIT_ON_CORE_THREAD = 0x02, CGO_INITIALIZED = 0x04 }
 Values that represent current state of the core object. More...
 

Method documentation

◆ _createPtr() [1/2]

static SPtr<Texture> _createPtr ( const TEXTURE_DESC desc)
static

Same as create() excepts it creates a pointer to the texture instead of a texture handle.

◆ _createPtr() [2/2]

static SPtr<Texture> _createPtr ( const SPtr< PixelData > &  pixelData,
int  usage = TU_DEFAULT,
bool  hwGammaCorrection = false 
)
static

Same as create() excepts it creates a pointer to the texture instead of a texture handle.

◆ calculateSize()

UINT32 calculateSize ( ) const
protected

Calculates the size of the texture, in bytes.

◆ create() [1/2]

static HTexture create ( const TEXTURE_DESC desc)
static

Creates a new empty texture.

Parameters
[in]descDescription of the texture to create.

◆ create() [2/2]

static HTexture create ( const SPtr< PixelData > &  pixelData,
int  usage = TU_DEFAULT,
bool  hwGammaCorrection = false 
)
static

Creates a new 2D or 3D texture initialized using the provided pixel data.

Texture will not have any mipmaps.

Parameters
[in]pixelDataData to initialize the texture width.
[in]usageDescribes planned texture use.
[in]hwGammaCorrectionIf true the texture data is assumed to have been gamma corrected and will be converted back to linear space when sampled on GPU.

◆ createCore()

SPtr<ct::CoreObject> createCore ( ) const
overrideprotectedvirtual

Creates an object that contains core thread specific data and methods for this CoreObject.

Can be null if such object is not required.

Reimplemented from CoreObject.

◆ createCPUBuffers()

void createCPUBuffers ( )
protected

Creates buffers used for caching of CPU texture data.

Note
Make sure to initialize all texture properties before calling this.

◆ getCore()

SPtr<ct::Texture> getCore ( ) const

Retrieves a core implementation of a texture usable only from the core thread.

◆ getProperties()

const TextureProperties& getProperties ( ) const

Returns properties that contain information about the texture.

◆ getRTTI()

RTTITypeBase* getRTTI ( ) const
overridevirtual

Returns an interface you can use to access class' Run Time Type Information.

Note

You must derive your own version of RTTITypeBase, in which you may encapsulate all reflection specific operations.

Implements IReflectable.

◆ initialize()

void initialize ( )
overrideprotectedvirtual

Initializes all the internal resources of this object.

Must be called right after construction. Generally you should call this from a factory method to avoid the issue where user forgets to call it.

Note

If this object require initialization on core thread initialization is not done immediately, and is instead just scheduled on the core thread. Otherwise the object is initialized immediately.

Reimplemented from CoreObject.

◆ readCachedData()

void readCachedData ( PixelData data,
UINT32  face = 0,
UINT32  mipLevel = 0 
)

Reads data from the cached system memory texture buffer into the provided buffer.

Parameters
[out]dataPre-allocated buffer of proper size and format where data will be read to. You can use TextureProperties::allocBuffer() to allocate a buffer of a correct format and size.
[in]faceTexture face to read from.
[in]mipLevelMipmap level to read from.
Note

The data read is the cached texture data. Any data written to the texture from the GPU or core thread will not be reflected in this data. Use readData() if you require those changes.

Note
The texture must have been created with TU_CPUCACHED usage otherwise this method will not return any data.

◆ readData()

AsyncOp readData ( const SPtr< PixelData > &  data,
UINT32  face = 0,
UINT32  mipLevel = 0 
)

Reads internal texture data to the provided previously allocated buffer.

Provided data buffer will be locked until the operation completes.

Parameters
[out]dataPre-allocated buffer of proper size and format where data will be read to. You can use TextureProperties::allocBuffer() to allocate a buffer of a correct format and size.
[in]faceTexture face to read from.
[in]mipLevelMipmap level to read from.
Returns
Async operation object you can use to track operation completion.
Note
This is an asynchronous method.

◆ updateCPUBuffers()

void updateCPUBuffers ( UINT32  subresourceIdx,
const PixelData data 
)
protected

Updates the cached CPU buffers with new data.

◆ writeData()

AsyncOp writeData ( const SPtr< PixelData > &  data,
UINT32  face = 0,
UINT32  mipLevel = 0,
bool  discardEntireBuffer = false 
)

Updates the texture with new data.

Provided data buffer will be locked until the operation completes.

Parameters
[in]dataPixel data to write. User must ensure it is in format and size compatible with the texture.
[in]faceTexture face to write to.
[in]mipLevelMipmap level to write to.
[in]discardEntireBufferWhen true the existing contents of the resource you are updating will be discarded. This can make the operation faster. Resources with certain buffer types might require this flag to be in a specific state otherwise the operation will fail.
Returns
Async operation object you can use to track operation completion.
Note
This is an asynchronous method.