CYIAssetTextureBase Class Reference

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 into the GPU memory. 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 TextureConfig &	GetConfiguration () 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 CYIString &	GetPath () const
CYIAssetLoadParams *	GetLoadParameters () const
virtual std::pair< size_t, size_t >	GetApproximateSize () const
bool	SetName (const CYIString &name)
const CYIString &	GetName () const
bool	Load ()
void	Unload ()
bool	IsLoaded () const
bool	Equals (const std::shared_ptr< CYIAsset > &pAsset)

Protected Member Functions
virtual std::shared_ptr< IYIGPUObject >	CreateGPUObject () 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< IYIGPUObject >	m_pGPUObject
RetentionPolicy	m_retentionPolicy
Static Protected Attributes inherited from CYIAsset
static ssize_t	INVALID_ID

Member Enumeration Documentation

Filtering

enum CYIAssetTextureBase::Filtering

strong

Minification and magnification rules.

Enumerator
Linear	Linear interpolation (used when the image is scaled).
Nearest	Nearest neighbor interpolation (used when image is scaled).

Usage

enum CYIAssetTextureBase::Usage

strong

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

enum CYIAssetTextureBase::WrapMode

strong

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.

Changing the wrap modes on an asset texture affects all uses of that asset, unless the CYIMaterial used with that asset has its own wrap mode set on it.

See also

CYIMaterial::SetWrapModes

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

See also

SetMipmappingEnabled

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:

• asset/YiAssetTextureBase.h