You.i Engine
CYIAssetTextureBase Class Referenceabstract

Detailed Description

This asset represents the base class for POT (Power Of Two) and NPOT (Non-Power Of Two) textures.

A derived class must delete any underlying resources and the associated texture, unless those resources are shared.

See also
CYIAssetHardware
CYIAssetTexture

#include <asset/YiAssetTextureBase.h>

Inheritance diagram for CYIAssetTextureBase:

Classes

struct  TextureConfig
 

Public Types

enum  Filtering {
  Filtering::Linear,
  Filtering::Nearest
}
 
enum  WrapMode {
  WrapMode::ClampToEdge,
  WrapMode::Mirror,
  WrapMode::Repeat
}
 
enum  Usage {
  Usage::Static,
  Usage::Dynamic,
  Usage::RenderTarget
}
 
- Public Types inherited from CYIAssetHardware
enum  RetentionPolicy {
  RetentionPolicy::Retain = 0,
  RetentionPolicy::Unload
}
 The CYIAssetHardware::RetentionPolicy enum specifies the retention policy of static hardware assets from the CPU memory once they are loaded onto the GPU. It is globally configurable, where new CYIAssetHardware will be making use of it and the can also change directly per assets. Be aware that on some platform, it is best to leave the assets retained on the CPU side when the platform lifecycle has the ability to destroy the graphic context while the app still runs, giving You.i Engine the ability to re-load every assets back onto GPU memory really fast. A good example of such platform would be Android. More...
 
- Public Types inherited from CYIAsset
enum  PathType {
  PathType::Absolute = 0,
  PathType::Relative
}
 

Public Member Functions

 CYIAssetTextureBase (Usage usage=Usage::Static)
 
virtual ~CYIAssetTextureBase () override
 
void AddDirtyRegion (const YI_RECT_REL &dirtyRectangle)
 
void GrowDirtyRegion (const YI_RECT_REL &dirtyRectangle)
 
void ClearDirtyRegions ()
 
const std::vector< YI_RECT_REL > & GetDirtyRegions () const
 
const TextureConfigGetConfiguration () const
 
virtual int32_t GetWidth () const
 
virtual int32_t GetHeight () const
 
IYIMaterialFactory::ColorSpace GetColorSpace () const
 
void SetConfiguration (const TextureConfig &config)
 
void SetMinificationFilter (Filtering minFilter=Filtering::Linear, Filtering magFilter=Filtering::Linear)
 
void SetMipmappingEnabled (bool enable)
 
bool IsMipmappingEnabled () const
 
void SetTextureWrap (WrapMode wrapS=WrapMode::ClampToEdge, WrapMode wrapT=WrapMode::ClampToEdge)
 
virtual bool HasExtendedDimensions () const
 
Usage GetUsage () const
 
virtual void ApplyRetainmentPolicy () override
 
- Public Member Functions inherited from CYIAssetHardware
 CYIAssetHardware ()
 
virtual ~CYIAssetHardware () override
 
virtual bool RequestHardwareLoad ()
 
virtual bool RequestHardwareUnload ()
 
virtual bool RequestInvalidate ()
 
virtual bool RequestRestore ()
 
virtual bool Prepare () override
 
const std::shared_ptr< IYIGPUObject > & GetGPUObject () const
 
bool IsLoadedOnGPU () const
 
RetentionPolicy GetRetentionPolicy () const
 
void SetRetentionPolicy (RetentionPolicy policy)
 
- Public Member Functions inherited from CYIAsset
virtual ~CYIAsset ()
 
const CYIStringGetPath () const
 
CYIAssetLoadParamsGetLoadParameters () const
 
virtual std::pair< size_t, size_tGetApproximateSize () const
 
bool SetName (const CYIString &name)
 
const CYIStringGetName () const
 
bool Load ()
 
void Unload ()
 
bool IsLoaded () const
 
bool Equals (const std::shared_ptr< CYIAsset > &pAsset)
 

Protected Member Functions

virtual std::shared_ptr< IYIGPUObjectCreateGPUObject () const override=0
 
virtual void OnUnload () override=0
 
virtual void DirtyEntireTexture ()
 
void SetWidth (int32_t width)
 
void SetHeight (int32_t height)
 
void SetColorSpace (IYIMaterialFactory::ColorSpace colorSpace)
 
- Protected Member Functions inherited from CYIAssetHardware
virtual void OnLoad () override
 
- Protected Member Functions inherited from CYIAsset
 CYIAsset ()
 
ssize_t GetID () const
 
void SetPath (const CYIString &path, PathType pathType)
 
void SetApproximateSize (size_t size)
 
void SetLoaded (bool assetLoaded)
 
void SetLoadParameters (std::unique_ptr< CYIAssetLoadParams > pParams)
 

Additional Inherited Members

- Protected Attributes inherited from CYIAssetHardware
bool m_hardwareLoadRequested
 
std::shared_ptr< IYIGPUObjectm_pGPUObject
 
RetentionPolicy m_retentionPolicy
 
- Static Protected Attributes inherited from CYIAsset
static ssize_t INVALID_ID
 

Member Enumeration Documentation

◆ Filtering

Minification and magnification rules.

Enumerator
Linear 

Linear interpolation (used when the image is scaled).

Nearest 

Nearest neighbor interpolation (used when image is scaled).

◆ Usage

Texture usage.

Enumerator
Static 

A static texture will never be modified again.

Dynamic 

A dynamic texture can be modified.

RenderTarget 

A texture that is to be used in a render target/frame buffer.

◆ WrapMode

Texture wrapping rules.

Warning
Not all devices support the use of WrapMode::Mirror or WrapMode::Repeat with non-power-of-two texture sizes. A power-of-two texture size is a texture which has a height and width that are a power-of-two, for example a 256x128 texture. If a device does not support this and the texture has a non-power-of-two texture size the texture will not be rendered. It is recommended when using these modes that the texture width and height are power-of-two.
Enumerator
ClampToEdge 

Clamp texture to edge of image. This wrap mode will repeat the last pixel on the edge in the direction for the texture coordinate to which it is applied.

Mirror 

Mirror texture coordinates. This wrap mode will draw the same image but mirrored horizontally or vertically in the direction for the texture coordinate to which it is applied.

Repeat 

Repeats the texture – often used for tiling a background. This wrap mode will repeat the image in the direction for the texture coordinate to which it is applied.

Constructor & Destructor Documentation

◆ CYIAssetTextureBase()

CYIAssetTextureBase::CYIAssetTextureBase ( Usage  usage = Usage::Static)

◆ ~CYIAssetTextureBase()

virtual CYIAssetTextureBase::~CYIAssetTextureBase ( )
overridevirtual

Member Function Documentation

◆ AddDirtyRegion()

void CYIAssetTextureBase::AddDirtyRegion ( const YI_RECT_REL dirtyRectangle)

Dirty a specific sub-image of the data. This function allows for users writing performance-critical applications to update the texture asset without requiring a copy of the entirety of the bitmap information.

Multiple calls to this function will result in multiple regions being updated, there is no overwrite. This object will not check for intersection of dirty rectangles, it is up to the user to provide the most efficient series of rectangles to be updated.

Note
All other modifications to the texture asset will dirty the entire image region. This function, along with GrowDirtyRegion, is the only means by which a specific subregion can be dirtied.
Avoid using both AddDirtyRegion and GrowDirtyRegion on the same texture. Doing so may result in overlapping regions, which can lead to inefficiencies.
See also
GrowDirtyRegion

◆ ApplyRetainmentPolicy()

virtual void CYIAssetTextureBase::ApplyRetainmentPolicy ( )
overridevirtual

Unloads CPU-side data buffer memory if the retainment policy is configured to unload instead of retaining it.

This function should only be used internally by the GPU object after the data has been uploaded onto the GPU. that some asset may chose to retain/unload cpu assets with additional conditions. For example, CYIAssetTextureBase won't unload the cpu asset if the asset is marked as being dynamic.

See also
SetRetentionPolicy
GetRetentionPolicy

Reimplemented from CYIAssetHardware.

◆ ClearDirtyRegions()

void CYIAssetTextureBase::ClearDirtyRegions ( )

Clear the dirty regions.

◆ CreateGPUObject()

virtual std::shared_ptr<IYIGPUObject> CYIAssetTextureBase::CreateGPUObject ( ) const
overrideprotectedpure virtual

Each sub-type must implement this function and returns an IYIGPUObject representing the hardware type.

Implements CYIAssetHardware.

Implemented in CYIAssetTextureRaw, CYIAssetTexture, and CYIAssetTextureFramebuffer.

◆ DirtyEntireTexture()

virtual void CYIAssetTextureBase::DirtyEntireTexture ( )
protectedvirtual

Marks the texture as dirty, meaning the associated texture resource needs to be updated.

◆ GetColorSpace()

IYIMaterialFactory::ColorSpace CYIAssetTextureBase::GetColorSpace ( ) const

Returns the color space used by this texture.

◆ GetConfiguration()

const TextureConfig& CYIAssetTextureBase::GetConfiguration ( ) const

Returns a reference to the TextureConfig structure of this asset. This structure contains all of the texture configuration properties.

◆ GetDirtyRegions()

const std::vector<YI_RECT_REL>& CYIAssetTextureBase::GetDirtyRegions ( ) const

Returns the dirty regions added using AddDirtyRegion().

◆ GetHeight()

virtual int32_t CYIAssetTextureBase::GetHeight ( ) const
virtual

Returns the height of the textured region. In the case of POT textures, this must return the height of the actual textured region and not the actual height of the texture.

Reimplemented in CYIAssetTexture.

◆ GetUsage()

Usage CYIAssetTextureBase::GetUsage ( ) const

Returns the usage for this texture. This value is immutable and is set in the CYIAssetTextureBase constructor.

◆ GetWidth()

virtual int32_t CYIAssetTextureBase::GetWidth ( ) const
virtual

Returns the width of the textured region. In the case of POT textures, this must return the width of the actual textured region and not the actual width of the texture.

Reimplemented in CYIAssetTexture.

◆ GrowDirtyRegion()

void CYIAssetTextureBase::GrowDirtyRegion ( const YI_RECT_REL dirtyRectangle)

Dirty a specific sub-image of the data. If at least one dirty region already exists, it is expanded to include both the original dirty region and dirtyRectangle.

This function allows for users writing performance-critical applications to update the texture asset without requiring a copy of the entirety of the bitmap information.

Note
All other modifications to the texture asset will dirty the entire image region. This function, along with GrowDirtyRegion, is the only means by which a specific subregion can be dirtied.
Avoid using both AddDirtyRegion and GrowDirtyRegion on the same texture. Doing so may result in overlapping regions, which can lead to inefficiencies.
See also
GrowDirtyRegion

◆ HasExtendedDimensions()

virtual bool CYIAssetTextureBase::HasExtendedDimensions ( ) const
virtual

Returns true if the texture's dimensions are different than the source dimensions. For example, if the texture is required to be power-of-two but the originating asset size is different, then this should return true.

◆ IsMipmappingEnabled()

bool CYIAssetTextureBase::IsMipmappingEnabled ( ) const

◆ OnUnload()

virtual void CYIAssetTextureBase::OnUnload ( )
overrideprotectedpure virtual

Reimplemented from CYIAsset.

Implemented in CYIAssetTextureRaw, CYIAssetTexture, and CYIAssetTextureFramebuffer.

◆ SetColorSpace()

void CYIAssetTextureBase::SetColorSpace ( IYIMaterialFactory::ColorSpace  colorSpace)
protected

Sets the color space of this texture. This does not perform color space conversions on the underlying data. Calling this function is used to instruct the renderer on how this texture should be loaded onto the GPU.

◆ SetConfiguration()

void CYIAssetTextureBase::SetConfiguration ( const TextureConfig config)

Convenience function for setting the texture configuration all at once

◆ SetHeight()

void CYIAssetTextureBase::SetHeight ( int32_t  height)
protected

Sets the height of the textured region. In POT texture implmentations, this should be the height of the textured sub-region and not necessarily the actual height.

◆ SetMinificationFilter()

void CYIAssetTextureBase::SetMinificationFilter ( Filtering  minFilter = Filtering::Linear,
Filtering  magFilter = Filtering::Linear 
)

Sets the rules for how the texture should be scaled. Magnification applies scaling to a texel when the size is caculated to be larger than a pixel. When a texel is calculated to be smaller than a pixel, the process is called minification. minFilter determines the rule to use for minifying the texture, and magFilter determines the rule to use for magnifying the texture. Both parameters default to YI_LINEAR.

CYIAssetTextureBase::Filtering::Linear means that adjacent pixels will be bilinearly filtered. CYIAssetTextureBase::Filtering::Nearest means that the nearest pixel will be selected.

◆ SetMipmappingEnabled()

void CYIAssetTextureBase::SetMipmappingEnabled ( bool  enable)

Enables or disables the generation and usage of mipmaps. Mipmapping is disabled by default.

Mipmapping is a technique in graphics rendering that improves the quality of textures when they are displayed on screen at a size significantly smaller than their original resolution. The texture is internally duplicated multiple times at smaller and smaller resolutions until a texture size of 1x1 is reached. This causes the texture to use approximately 1/3 more space than the original texture. Non power-of-two textures may use significantly more memory. The GPU will then choose the texture with the size that is closest to what will be displayed on screen.

Mipmapping should be used on textures that look pixelated and jagged due to being drawn at a smaller size than the original texture.

This will adjust the minification filter setting internally to allow the use of the generated mipmaps.

Disabling mipmapping on a texture which is already loaded with mipmapping enabled will have no effect.

See also
SetMinificationFilter

◆ SetTextureWrap()

void CYIAssetTextureBase::SetTextureWrap ( WrapMode  wrapS = WrapMode::ClampToEdge,
WrapMode  wrapT = WrapMode::ClampToEdge 
)

Sets the rules for how the texture coordinates should be wrapped if they extend past the bounds (< 0 or > 1). wrapS determines how to wrap on the s axis (horizontal axis), wrapT determines how to wrap on the t axis (vertical axis). Both parameters default to WrapMode::ClampToEdge.

See also
CYIAssetTextureBase::WrapMode::ClampToEdge will clamp to the last pixel value on the edge.
CYIAssetTextureBase::WrapMode::Repeat will result in tiling
CYIAssetTextureBase::WrapMode::Mirror will result in mirrored tiling

◆ SetWidth()

void CYIAssetTextureBase::SetWidth ( int32_t  width)
protected

Sets the width of the textured region. In POT texture implmentations, this should be the width of the textured sub-region and not necessarily the actual width.


The documentation for this class was generated from the following file: