Ogre::TextureGpu Class Reference

#include <OgreTextureGpu.h>

Inheritance diagram for Ogre::TextureGpu:

Public Member Functions
	TextureGpu (GpuPageOutStrategy::GpuPageOutStrategy pageOutStrategy, VaoManager *vaoManager, IdString name, uint32 textureFlags, TextureTypes::TextureTypes initialType, TextureGpuManager *textureManager)
	~TextureGpu () override
virtual void	_autogenerateMipmaps (CopyEncTransitionMode::CopyEncTransitionMode transitionMode=CopyEncTransitionMode::Auto)=0
	Tells the API to let the HW autogenerate mipmaps. More...
uint8 *	_getSysRamCopy (uint8 mipLevel)
TextureBox	_getSysRamCopyAsBox (uint8 mipLevel)
size_t	_getSysRamCopyBytesPerImage (uint8 mipLevel)
	Note: Returns non-zero even if there is no system ram copy. More...
uint32	_getSysRamCopyBytesPerRow (uint8 mipLevel)
	Note: Returns non-zero even if there is no system ram copy. More...
virtual bool	_isDataReadyImpl () const =0
	For internal use. More...
bool	_isManualTextureFlagPresent () const
void	_notifySysRamDownloadIsReady (uint8 *sysRamPtr, bool resyncOnly)
	Do not call directly. More...
virtual void	_notifyTextureSlotChanged (const TexturePool *newPool, uint16 slice)
void	_resetTextureManager ()
void	_resolveTo (TextureGpu *resolveTexture)
	Immediately resolves this texture to the resolveTexture argument. More...
virtual void	_setDepthBufferDefaults (uint16 depthBufferPoolId, bool preferDepthTexture, PixelFormatGpu desiredDepthBufferFormat)
	These 3 values are used as defaults for the compositor to use, but they may be explicitly overriden by a RenderPassDescriptor. More...
virtual void	_setNextLayout (ResourceLayout::Layout layout)
	Sets the layout the texture should be transitioned to after the next copy operation (once the copy encoder gets closed) More...
void	_setSampleDescription (SampleDescription desc, SampleDescription validatedSampleDesc)
	For internal use. More...
void	_setSourceType (uint8 type)
virtual void	_setToDisplayDummyTexture ()=0
void	_syncGpuResidentToSystemRam ()
	Forces downloading data from GPU to CPU, usually because the data on GPU changed and we're in strategy AlwaysKeepSystemRamCopy. More...
void	_transitionTo (GpuResidency::GpuResidency newResidency, uint8 *sysRamCopy, bool autoDeleteSysRamCopy=true)
	This function may be called manually (if user is manually managing a texture) or automatically (e.g. More...
void	addListener (TextureGpuListener *listener)
bool	allowsAutoMipmaps () const
void	copyContentsToMemory (TextureBox src, TextureBox dst, PixelFormatGpu dstFormat, bool automaticResolve=true)
	Writes the current contents of the render target to the memory. More...
void	copyParametersFrom (TextureGpu *src)
virtual void	copyTo (TextureGpu *dst, const TextureBox &dstBox, uint8 dstMipLevel, const TextureBox &srcBox, uint8 srcMipLevel, bool keepResolvedTexSynced=true, CopyEncTransitionMode::CopyEncTransitionMode srcTransitionMode=CopyEncTransitionMode::Auto, CopyEncTransitionMode::CopyEncTransitionMode dstTransitionMode=CopyEncTransitionMode::Auto)
virtual ResourceLayout::Layout	getCurrentLayout () const
virtual void	getCustomAttribute (IdString name, void *pData)
ResourceLayout::Layout	getDefaultLayout (bool bIgnoreDiscardableFlag=false) const
uint32	getDepth () const
	For TypeCube & TypeCubeArray, this value returns 1. More...
virtual uint16	getDepthBufferPoolId () const
uint32	getDepthOrSlices () const
virtual PixelFormatGpu	getDesiredDepthBufferFormat () const
TextureBox	getEmptyBox (uint8 mipLevel)
uint32	getHeight () const
uint32	getInternalHeight () const
	Real API height accounting for TextureGpu::getOrientationMode. See getInternalWidth. More...
uint16	getInternalSliceStart () const
TextureTypes::TextureTypes	getInternalTextureType () const
uint32	getInternalWidth () const
	Real API width accounting for TextureGpu::getOrientationMode If orientation mode is 90° or 270° then getInternalWidth returns the height and getInternalHeight returns the width. More...
const vector< TextureGpuListener * >::type &	getListeners () const
String	getNameStr () const override
	Note: This returns the alias name of the texture. More...
uint8	getNumMipmaps () const
uint32	getNumSlices () const
	For TypeCube this value returns 6. More...
virtual OrientationMode	getOrientationMode () const
PixelFormatGpu	getPixelFormat () const
virtual bool	getPreferDepthTexture () const
virtual String	getRealResourceNameStr () const
	Returns the real name (e.g. disk in file) of the resource. More...
SampleDescription	getRequestedSampleDescription () const
	Returns original requested sample description, i.e. the raw input to setSampleDescription. More...
virtual String	getResourceGroupStr () const
SampleDescription	getSampleDescription () const
	Returns effective sample description supported by the API. More...
String	getSettingsDesc () const
size_t	getSizeBytes () const
	Returns total size in bytes used in GPU by this texture (not by its pool) including mipmaps. More...
uint8	getSourceType () const
	This setting is for where the texture is created, e.g. More...
virtual void	getSubsampleLocations (vector< Vector2 >::type locations)=0
	Get the MSAA subsample locations. More...
TextureGpuManager *	getTextureManager () const
const TexturePool *	getTexturePool () const
uint32	getTexturePoolId () const
TextureTypes::TextureTypes	getTextureType () const
uint32	getWidth () const
bool	hasAutomaticBatching () const
bool	hasAutoMipmapAuto () const
bool	hasEquivalentParameters (TextureGpu *other) const
bool	hasMsaaExplicitResolves () const
bool	isDataReady () const
	True if this texture is fully ready to be used for displaying. More...
bool	isDiscardableContent () const
bool	isManualTexture () const
bool	isMetadataReady () const
	It is threadsafe to call this function from main thread. More...
virtual bool	isMsaaPatternSupported (MsaaPatterns::MsaaPatterns pattern)
bool	isMultisample () const
virtual bool	isOpenGLRenderWindow () const
	OpenGL RenderWindows are a bit specific: More...
bool	isPoolOwner () const
bool	isReinterpretable () const
bool	isRenderToTexture () const
bool	isRenderWindowSpecific () const
bool	isTexture () const
bool	isTextureGpu () const override
bool	isTilerMemoryless () const
bool	isUav () const
void	notifyAllListenersTextureChanged (uint32 reason, void *extraData=0)
virtual void	notifyDataIsReady ()=0
	Notifies it is safe to use the real data. Everything has been uploaded. More...
bool	prefersLoadingFromFileAsSRGB () const
void	removeListener (TextureGpuListener *listener)
bool	requiresTextureFlipping () const
void	scheduleReupload (Image2 *image=0, bool autoDeleteImage=true, bool bSkipMultiload=false)
	There are times where you want to reload a texture again (e.g. More...
void	scheduleTransitionTo (GpuResidency::GpuResidency nextResidency, Image2 *image=0, bool autoDeleteImage=true, bool bSkipMultiload=false)
	Same as unsafeScheduleTransitionTo, but first checks if we're already in the residency state we want to go to, or if it has already been scheduled; thus it can be called multiple times. More...
void	setNumMipmaps (uint8 numMipmaps)
virtual void	setOrientationMode (OrientationMode orientationMode)
	Sets the given orientation. More...
void	setPixelFormat (PixelFormatGpu pixelFormat)
	Sets the pixel format. More...
void	setResolution (uint32 width, uint32 height, uint32 depthOrSlices=1u)
void	setSampleDescription (SampleDescription desc)
void	setTexturePoolId (uint32 poolId)
	2D Texture with automatic batching will be merged with other textures into the same pool as one big 2D Array texture behind the scenes. More...
virtual void	setTextureType (TextureTypes::TextureTypes textureType)
virtual bool	supportsAsDepthBufferFor (TextureGpu *colourTarget) const
virtual void	swapBuffers ()
	Only valid for TextureGpu classes. More...
void	unsafeScheduleTransitionTo (GpuResidency::GpuResidency nextResidency, Image2 *image=0, bool autoDeleteImage=true, bool bSkipMultiload=false)
	Schedules an async transition in residency. More...
void	waitForData ()
	Blocks main thread until data is ready. More...
void	waitForMetadata ()
	Blocks main thread until metadata is ready. More...
void	writeContentsToFile (const String &filename, uint8 minMip, uint8 maxMip, bool automaticResolve=true)
	Writes the current contents of the render target to the named file. More...
Public Member Functions inherited from Ogre::GpuTrackedResource
virtual	~GpuTrackedResource ()
Public Member Functions inherited from Ogre::GpuResource
	GpuResource (GpuPageOutStrategy::GpuPageOutStrategy pageOutStrategy, VaoManager *vaoManager, IdString name)
virtual	~GpuResource ()
void	_addPendingResidencyChanges (uint32 value)
void	_setNextResidencyStatus (GpuResidency::GpuResidency nextResidency)
GpuPageOutStrategy::GpuPageOutStrategy	getGpuPageOutStrategy () const
IdString	getName () const
GpuResidency::GpuResidency	getNextResidencyStatus () const
	When getResidencyStatus() != getNextResidencyStatus(), residency changes happen in the main thread, while some preparation may be happening in the background. More...
uint32	getPendingResidencyChanges () const
	Returns the number of pending residency changes. More...
GpuResidency::GpuResidency	getResidencyStatus () const

Static Public Attributes
static OrientationMode	msDefaultOrientationMode
	PUBLIC VARIABLE. More...
static const IdString	msFinalTextureBuffer
static const IdString	msMsaaTextureBuffer

Detailed Description

Remarks

Internal layout of data in memory:

        Mip0 -> Slice 0, Slice 1, ..., Slice N
        Mip1 -> Slice 0, Slice 1, ..., Slice N
        ...
        MipN -> Slice 0, Slice 1, ..., Slice N

The layout for 3D volume and array textures is the same. The only thing that changes is that for 3D volumes, the number of slices also decreases with each mip, while for array textures it is kept constant.

For 1D array textures, the number of slices is stored in mDepthOrSlices, not in Height.

For code reference, look at _getSysRamCopyAsBox implementation, and TextureBox::at Each row of pixels is aligned to 4 bytes (except for compressed formats that require more strict alignments, such as alignment to the block).

A TextureGpu loaded from file has the following life cycle, usually:

1. At creation it's mResidencyStatus = GpuResidency::OnStorage
2. Loading is scheduled via scheduleTransitionTo. mNextResidencyStatus = GpuResidency::Resident
3. Texture transitions to resident. mResidencyStatus = GpuResidency::Resident isMetadataReady returns true. How fast this happens depends on whether there was a metadata cache or not.
4. If there is a metadata cache, and the cache turned out to be wrong (e.g. it lied or was out of date), the texture will transition back to OnStorage and the whole process repeats from step 1.
5. Texture finishes loading. notifyDataIsReady gets called and now isDataReady returns true.

Constructor & Destructor Documentation

TextureGpu()

Ogre::TextureGpu::TextureGpu	(	GpuPageOutStrategy::GpuPageOutStrategy	pageOutStrategy,
		VaoManager *	vaoManager,
		IdString	name,
		uint32	textureFlags,
		TextureTypes::TextureTypes	initialType,
		TextureGpuManager *	textureManager
	)

~TextureGpu()

Ogre::TextureGpu::~TextureGpu ( )

override

Member Function Documentation

_autogenerateMipmaps()

virtual void Ogre::TextureGpu::_autogenerateMipmaps ( CopyEncTransitionMode::CopyEncTransitionMode  transitionMode = CopyEncTransitionMode::Auto )

pure virtual

Tells the API to let the HW autogenerate mipmaps.

Assumes allowsAutoMipmaps() == true and isRenderToTexture() == true

Parameters

transitionMode

See CopyEncTransitionMode::CopyEncTransitionMode

Implemented in Ogre::VulkanTextureGpu, Ogre::NULLTextureGpu, Ogre::MetalTextureGpu, Ogre::GL3PlusTextureGpu, and Ogre::D3D11TextureGpu.

_getSysRamCopy()

uint8* Ogre::TextureGpu::_getSysRamCopy

(

uint8

mipLevel

)

_getSysRamCopyAsBox()

TextureBox Ogre::TextureGpu::_getSysRamCopyAsBox

(

uint8

mipLevel

)

_getSysRamCopyBytesPerImage()

size_t Ogre::TextureGpu::_getSysRamCopyBytesPerImage

(

uint8

mipLevel

)

Note: Returns non-zero even if there is no system ram copy.

_getSysRamCopyBytesPerRow()

uint32 Ogre::TextureGpu::_getSysRamCopyBytesPerRow

(

uint8

mipLevel

)

Note: Returns non-zero even if there is no system ram copy.

_isDataReadyImpl()

virtual bool Ogre::TextureGpu::_isDataReadyImpl ( ) const

pure virtual

For internal use.

Do not call directly.

This function is the same isDataReady except it ignores pending residency changes, which is important when TextureGpuManager needs to know this information but the TextureGpu is transitioning (thus mPendingResidencyChanges is in an inconsistent state)

Implemented in Ogre::VulkanTextureGpuWindow, Ogre::VulkanTextureGpu, Ogre::NULLTextureGpu, Ogre::MetalTextureGpuWindow, Ogre::MetalTextureGpu, Ogre::GL3PlusTextureGpuWindow, Ogre::GL3PlusTextureGpu, Ogre::D3D11TextureGpuWindow, and Ogre::D3D11TextureGpu.

_isManualTextureFlagPresent()

bool Ogre::TextureGpu::_isManualTextureFlagPresent

(

)

const

_notifySysRamDownloadIsReady()

void Ogre::TextureGpu::_notifySysRamDownloadIsReady	(	uint8 *	sysRamPtr,
		bool	resyncOnly
	)

Do not call directly.

Will change mResidencyStatus from GpuResidency::Resident to GpuResidency::OnSystemRam

_notifyTextureSlotChanged()

virtual void Ogre::TextureGpu::_notifyTextureSlotChanged ( const TexturePool *  newPool, uint16  slice  )

virtual

Reimplemented in Ogre::VulkanTextureGpuWindow, Ogre::VulkanTextureGpu, Ogre::MetalTextureGpuWindow, Ogre::MetalTextureGpu, Ogre::GL3PlusTextureGpuHeadlessWindow, Ogre::GL3PlusTextureGpuWindow, Ogre::GL3PlusTextureGpu, Ogre::D3D11TextureGpuWindow, and Ogre::D3D11TextureGpu.

_resetTextureManager()

void Ogre::TextureGpu::_resetTextureManager

(

)

_resolveTo()

void Ogre::TextureGpu::_resolveTo

(

TextureGpu *

resolveTexture

)

Immediately resolves this texture to the resolveTexture argument.

Source must be MSAA texture, destination must be non-MSAA.

Remarks

This function may be slow on some APIs and should only be used when required, for example, to capture the screen from an explicit MSAA target and save it to disk only on user demand. If you need to call this often (like once per frame or more), then consider setting a Compositor with CompositorNode::mLocalRtvs::resolveTextureName set so that the compositor automatically resolves the texture every frame as efficiently as possible.

_setDepthBufferDefaults()

virtual void Ogre::TextureGpu::_setDepthBufferDefaults ( uint16  depthBufferPoolId, bool  preferDepthTexture, PixelFormatGpu  desiredDepthBufferFormat  )

virtual

These 3 values are used as defaults for the compositor to use, but they may be explicitly overriden by a RenderPassDescriptor.

Particularly required when passing the textures between nodes as input and output (since only the TextureGpu pointer is passed, and thus this information is lost)

Remarks

Changing these settings won't take immediate effect because they're only used when creating the compositor.

Parameters

depthBufferPoolId	Sets the pool ID this RenderTarget should query from. Default value is POOL_DEFAULT. Set to POOL_NO_DEPTH to avoid using a DepthBuffer (or manually controlling it)
preferDepthTexture	Whether this RT should be attached to a depth texture, or a regular depth buffer. On older GPUs, preferring depth textures may result in certain depth precisions to not be available (or use integer precision instead of floating point, etc). True to use depth textures. False otherwise (default).
desiredDepthBufferFormat	Ogre will try to honour this request, but if it's not supported, you may get lower precision. All formats will try to fallback to PF_D24_UNORM_S8_UINT if not supported. Must be one of the following: PFG_D24_UNORM_S8_UINT PFG_D16_UNORM PFG_D32_FLOAT PFG_D32_FLOAT_X24_S8_UINT

Reimplemented in Ogre::VulkanTextureGpuRenderTarget, Ogre::NULLTextureGpuRenderTarget, Ogre::MetalTextureGpuRenderTarget, Ogre::GL3PlusTextureGpuRenderTarget, and Ogre::D3D11TextureGpuRenderTarget.

_setNextLayout()

virtual void Ogre::TextureGpu::_setNextLayout ( ResourceLayout::Layout  layout )

virtual

Sets the layout the texture should be transitioned to after the next copy operation (once the copy encoder gets closed)

This is specific to Vulkan & D3D12

Reimplemented in Ogre::VulkanTextureGpu.

_setSampleDescription()

void Ogre::TextureGpu::_setSampleDescription	(	SampleDescription	desc,
		SampleDescription	validatedSampleDesc
	)

For internal use.

_setSourceType()

void Ogre::TextureGpu::_setSourceType

(

uint8

type

)

_setToDisplayDummyTexture()

virtual void Ogre::TextureGpu::_setToDisplayDummyTexture ( )

pure virtual

Implemented in Ogre::VulkanTextureGpuWindow, Ogre::VulkanTextureGpu, Ogre::NULLTextureGpu, Ogre::MetalTextureGpuWindow, Ogre::MetalTextureGpu, Ogre::GL3PlusTextureGpuWindow, Ogre::GL3PlusTextureGpu, Ogre::D3D11TextureGpuWindow, and Ogre::D3D11TextureGpu.

_syncGpuResidentToSystemRam()

void Ogre::TextureGpu::_syncGpuResidentToSystemRam

(

)

Forces downloading data from GPU to CPU, usually because the data on GPU changed and we're in strategy AlwaysKeepSystemRamCopy.

May stall.

_transitionTo()

void Ogre::TextureGpu::_transitionTo	(	GpuResidency::GpuResidency	newResidency,
		uint8 *	sysRamCopy,
		bool	autoDeleteSysRamCopy = true
	)

This function may be called manually (if user is manually managing a texture) or automatically (e.g.

loading from file, or automatic batching is enabled) Once you call this function, you're no longer in OnStorage mode; and will transition to either OnSystemRam or Resident depending on whether auto batching is enabled.

Remarks

Do NOT call this function yourself if you've created this function with AutomaticBatching as Ogre will call this, from a worker thread!

Make sure you're done using mSysRamCopy before calling this function, as we may free that pointer (unless autoDeleteSysRamCopyOnResident = false).

If you're calling _transitionTo yourself (i.e. you're not using scheduleTransitionTo) then you'll need to call _setNextResidencyStatus too, so that both getResidencyStatus and getNextResidencyStatus agree.

Parameters

sysRamCopy

System RAM copy that backs this GPU data. May be null. Must've been allocated with OGRE_MALLOC_SIMD( size, MEMCATEGORY_RESOURCE ); We will deallocate it. MUST respect _getSysRamCopyBytesPerRow & _getSysRamCopyBytesPerImage. If in doubt, use PixelFormatGpuUtils::getSizeBytes with rowAlignment = 4u;

This param must be nullptr or equal to get_getSysRamCopy when going from Resident to OnSystemRam and strategy is not AlwaysKeepSystemRamCopy; as we will async download the content from the GPU.

Parameters

autoDeleteSysRamCopy

When true, we free mSysRamCopy as we should. When false, caller is responsible for deleting this pointer else it will leak!

addListener()

void Ogre::TextureGpu::addListener

(

TextureGpuListener *

listener

)

allowsAutoMipmaps()

bool Ogre::TextureGpu::allowsAutoMipmaps

(

)

const

copyContentsToMemory()

void Ogre::TextureGpu::copyContentsToMemory	(	TextureBox	src,
		TextureBox	dst,
		PixelFormatGpu	dstFormat,
		bool	automaticResolve = true
	)

Writes the current contents of the render target to the memory.

copyParametersFrom()

void Ogre::TextureGpu::copyParametersFrom

(

TextureGpu *

src

)

copyTo()

virtual void Ogre::TextureGpu::copyTo ( TextureGpu *  dst, const TextureBox &  dstBox, uint8  dstMipLevel, const TextureBox &  srcBox, uint8  srcMipLevel, bool  keepResolvedTexSynced = true, CopyEncTransitionMode::CopyEncTransitionMode  srcTransitionMode = CopyEncTransitionMode::Auto, CopyEncTransitionMode::CopyEncTransitionMode  dstTransitionMode = CopyEncTransitionMode::Auto  )

virtual

Parameters

dst
dstBox
dstMipLevel
srcBox
srcMipLevel
keepResolvedTexSynced	When true, if dst is an MSAA texture and is implicitly resolved (i.e. dst->hasMsaaExplicitResolves() == false); the resolved texture is also kept up to date.

Typically the reason to set this to false is if you plane on rendering more stuff to dst texture and then resolve.

Parameters

srcTransitionMode	Transition mode for 'this'
dstTransitionMode	Transition mode for 'dst'

Reimplemented in Ogre::VulkanTextureGpu, Ogre::MetalTextureGpu, Ogre::GL3PlusTextureGpu, and Ogre::D3D11TextureGpu.

getCurrentLayout()

virtual ResourceLayout::Layout Ogre::TextureGpu::getCurrentLayout ( ) const

virtual

Reimplemented in Ogre::VulkanTextureGpu.

getCustomAttribute()

virtual void Ogre::TextureGpu::getCustomAttribute ( IdString  name, void *  pData  )

inlinevirtual

Reimplemented in Ogre::VulkanTextureGpuWindow, Ogre::VulkanTextureGpu, Ogre::MetalTextureGpuWindow, Ogre::MetalTextureGpu, Ogre::GL3PlusTextureGpuHeadlessWindow, Ogre::GL3PlusTextureGpuWindow, Ogre::GL3PlusTextureGpu, Ogre::D3D11TextureGpuWindow, and Ogre::D3D11TextureGpu.

getDefaultLayout()

ResourceLayout::Layout Ogre::TextureGpu::getDefaultLayout

(

bool

bIgnoreDiscardableFlag = false

)

const

getDepth()

uint32 Ogre::TextureGpu::getDepth

(

)

const

For TypeCube & TypeCubeArray, this value returns 1.

getDepthBufferPoolId()

virtual uint16 Ogre::TextureGpu::getDepthBufferPoolId ( ) const

virtual

Reimplemented in Ogre::VulkanTextureGpuRenderTarget, Ogre::NULLTextureGpuRenderTarget, Ogre::MetalTextureGpuRenderTarget, Ogre::GL3PlusTextureGpuRenderTarget, and Ogre::D3D11TextureGpuRenderTarget.

getDepthOrSlices()

uint32 Ogre::TextureGpu::getDepthOrSlices

(

)

const

getDesiredDepthBufferFormat()

virtual PixelFormatGpu Ogre::TextureGpu::getDesiredDepthBufferFormat ( ) const

virtual

Reimplemented in Ogre::VulkanTextureGpuRenderTarget, Ogre::NULLTextureGpuRenderTarget, Ogre::MetalTextureGpuRenderTarget, Ogre::GL3PlusTextureGpuRenderTarget, and Ogre::D3D11TextureGpuRenderTarget.

getEmptyBox()

TextureBox Ogre::TextureGpu::getEmptyBox

(

uint8

mipLevel

)

getHeight()

uint32 Ogre::TextureGpu::getHeight

(

)

const

getInternalHeight()

uint32 Ogre::TextureGpu::getInternalHeight

(

)

const

Real API height accounting for TextureGpu::getOrientationMode. See getInternalWidth.

getInternalSliceStart()

uint16 Ogre::TextureGpu::getInternalSliceStart

(

)

const

getInternalTextureType()

TextureTypes::TextureTypes Ogre::TextureGpu::getInternalTextureType

(

)

const

getInternalWidth()

uint32 Ogre::TextureGpu::getInternalWidth

(

)

const

Real API width accounting for TextureGpu::getOrientationMode If orientation mode is 90° or 270° then getInternalWidth returns the height and getInternalHeight returns the width.

getListeners()

const vector<TextureGpuListener *>::type& Ogre::TextureGpu::getListeners

(

)

const

getNameStr()

String Ogre::TextureGpu::getNameStr ( ) const

overridevirtual

Note: This returns the alias name of the texture.

See TextureGpuManager::createOrRetrieveTexture

Reimplemented from Ogre::GpuResource.

getNumMipmaps()

uint8 Ogre::TextureGpu::getNumMipmaps

(

)

const

getNumSlices()

uint32 Ogre::TextureGpu::getNumSlices

(

)

const

For TypeCube this value returns 6.

For TypeCubeArray, value returns numSlices * 6u.

getOrientationMode()

virtual OrientationMode Ogre::TextureGpu::getOrientationMode ( ) const

virtual

Reimplemented in Ogre::VulkanTextureGpuRenderTarget, Ogre::MetalTextureGpuRenderTarget, Ogre::GL3PlusTextureGpuRenderTarget, and Ogre::D3D11TextureGpuRenderTarget.

getPixelFormat()

PixelFormatGpu Ogre::TextureGpu::getPixelFormat

(

)

const

getPreferDepthTexture()

virtual bool Ogre::TextureGpu::getPreferDepthTexture ( ) const

virtual

Reimplemented in Ogre::VulkanTextureGpuRenderTarget, Ogre::NULLTextureGpuRenderTarget, Ogre::MetalTextureGpuRenderTarget, Ogre::GL3PlusTextureGpuRenderTarget, and Ogre::D3D11TextureGpuRenderTarget.

getRealResourceNameStr()

virtual String Ogre::TextureGpu::getRealResourceNameStr ( ) const

virtual

Returns the real name (e.g. disk in file) of the resource.

getRequestedSampleDescription()

SampleDescription Ogre::TextureGpu::getRequestedSampleDescription

(

)

const

Returns original requested sample description, i.e. the raw input to setSampleDescription.

getResourceGroupStr()

virtual String Ogre::TextureGpu::getResourceGroupStr ( ) const

virtual

getSampleDescription()

SampleDescription Ogre::TextureGpu::getSampleDescription

(

)

const

Returns effective sample description supported by the API.

Note it's only useful after having transitioned to resident.

getSettingsDesc()

String Ogre::TextureGpu::getSettingsDesc

(

)

const

getSizeBytes()

size_t Ogre::TextureGpu::getSizeBytes

(

)

const

Returns total size in bytes used in GPU by this texture (not by its pool) including mipmaps.

getSourceType()

uint8 Ogre::TextureGpu::getSourceType

(

)

const

This setting is for where the texture is created, e.g.

its a compositor texture, a shadow texture or standard texture loaded for a mesh etc...

This value is merely for statistical tracking purposes

getSubsampleLocations()

virtual void Ogre::TextureGpu::getSubsampleLocations ( vector< Vector2 >::type  locations )

pure virtual

Get the MSAA subsample locations.

mSampleDescription.pattern must not be MsaaPatterns::Undefined.

Parameters

locations

Outputs an array with the locations for each subsample. Values are in range [-1; 1]

Implemented in Ogre::VulkanTextureGpuWindow, Ogre::VulkanTextureGpu, Ogre::NULLTextureGpu, Ogre::MetalTextureGpu, Ogre::GL3PlusTextureGpuWindow, Ogre::GL3PlusTextureGpu, Ogre::D3D11TextureGpuWindow, and Ogre::D3D11TextureGpu.

getTextureManager()

TextureGpuManager* Ogre::TextureGpu::getTextureManager

(

)

const

getTexturePool()

const TexturePool* Ogre::TextureGpu::getTexturePool ( ) const

inline

getTexturePoolId()

uint32 Ogre::TextureGpu::getTexturePoolId ( ) const

inline

getTextureType()

TextureTypes::TextureTypes Ogre::TextureGpu::getTextureType

(

)

const

getWidth()

uint32 Ogre::TextureGpu::getWidth

(

)

const

hasAutomaticBatching()

bool Ogre::TextureGpu::hasAutomaticBatching

(

)

const

hasAutoMipmapAuto()

bool Ogre::TextureGpu::hasAutoMipmapAuto

(

)

const

hasEquivalentParameters()

bool Ogre::TextureGpu::hasEquivalentParameters

(

TextureGpu *

other

)

const

hasMsaaExplicitResolves()

bool Ogre::TextureGpu::hasMsaaExplicitResolves

(

)

const

isDataReady()

bool Ogre::TextureGpu::isDataReady

(

)

const

True if this texture is fully ready to be used for displaying.

IMPORTANT: Always returns true if getResidencyStatus != GpuResidency::Resident and there are no pending residency transitions.

Returns false while there are pending residency status

If this is true, then isMetadataReady is also true. See isMetadataReady.

isDiscardableContent()

bool Ogre::TextureGpu::isDiscardableContent

(

)

const

isManualTexture()

bool Ogre::TextureGpu::isManualTexture

(

)

const

isMetadataReady()

bool Ogre::TextureGpu::isMetadataReady

(

)

const

It is threadsafe to call this function from main thread.

If this returns false, then the following functions are not threadsafe: Setters must not be called, and getters may change from a worker thread:

• setResolution
• getWidth, getHeight, getDepth, getDepthOrSlices, getNumSlices
• set/getPixelFormat
• set/getNumMipmaps
• set/getTextureType
• getTexturePool Note that this function may return true but the worker thread may still be uploading to this texture. Use isDataReady to see if the worker thread is fully done with this texture.

Remarks

Function for querying/waiting for data and metadata to be ready are for blocking the main thread when a worker thread is loading the texture from file or a listener (i.e. isManualTexture returns false) otherwise you don't need to call these functions.

isMsaaPatternSupported()

virtual bool Ogre::TextureGpu::isMsaaPatternSupported ( MsaaPatterns::MsaaPatterns  pattern )

virtual

Reimplemented in Ogre::D3D11TextureGpu.

isMultisample()

bool Ogre::TextureGpu::isMultisample

(

)

const

isOpenGLRenderWindow()

virtual bool Ogre::TextureGpu::isOpenGLRenderWindow ( ) const

virtual

OpenGL RenderWindows are a bit specific:

• Their origins are upside down. Which means we need to flip Y.
• They can access resolved contents of MSAA even if hasMsaaExplicitResolves = true
• Headless windows return false since internally they're FBOs. However isRenderWindowSpecific will return true

Reimplemented in Ogre::GL3PlusTextureGpuHeadlessWindow, and Ogre::GL3PlusTextureGpuWindow.

isPoolOwner()

bool Ogre::TextureGpu::isPoolOwner

(

)

const

isReinterpretable()

bool Ogre::TextureGpu::isReinterpretable

(

)

const

isRenderToTexture()

bool Ogre::TextureGpu::isRenderToTexture

(

)

const

isRenderWindowSpecific()

bool Ogre::TextureGpu::isRenderWindowSpecific

(

)

const

isTexture()

bool Ogre::TextureGpu::isTexture

(

)

const

isTextureGpu()

bool Ogre::TextureGpu::isTextureGpu ( ) const

overridevirtual

Reimplemented from Ogre::GpuTrackedResource.

isTilerMemoryless()

bool Ogre::TextureGpu::isTilerMemoryless ( ) const

inline

References Ogre::TextureFlags::TilerMemoryless.

isUav()

bool Ogre::TextureGpu::isUav

(

)

const

notifyAllListenersTextureChanged()

void Ogre::TextureGpu::notifyAllListenersTextureChanged	(	uint32	reason,
		void *	extraData = 0
	)

notifyDataIsReady()

virtual void Ogre::TextureGpu::notifyDataIsReady ( )

pure virtual

Notifies it is safe to use the real data. Everything has been uploaded.

Implemented in Ogre::VulkanTextureGpuWindow, Ogre::VulkanTextureGpu, Ogre::NULLTextureGpu, Ogre::MetalTextureGpuWindow, Ogre::MetalTextureGpu, Ogre::GL3PlusTextureGpuWindow, Ogre::GL3PlusTextureGpu, Ogre::D3D11TextureGpuWindow, and Ogre::D3D11TextureGpu.

prefersLoadingFromFileAsSRGB()

bool Ogre::TextureGpu::prefersLoadingFromFileAsSRGB

(

)

const

removeListener()

void Ogre::TextureGpu::removeListener

(

TextureGpuListener *

listener

)

requiresTextureFlipping()

bool Ogre::TextureGpu::requiresTextureFlipping

(

)

const

scheduleReupload()

void Ogre::TextureGpu::scheduleReupload	(	Image2 *	image = 0,
		bool	autoDeleteImage = true,
		bool	bSkipMultiload = false
	)

There are times where you want to reload a texture again (e.g.

file on disk changed, uploading a new Image2, etc) without visual disruption.

e.g. if you were to call:

tex->scheduleTransitionTo( GpuResidency::OnStorage );
tex->scheduleTransitionTo( GpuResidency::Resident, ... );

you'll achieve the same result, however the texture becomes immediately unavailable causing a few frames were all the user sees is a blank texture until it is fully reloaded.

This routine allows for an in-place hot-reload, where the old texture is swapped for the new one once it's done loading.

This is also faster because DescriptorTextureSets don't change

Remarks

1. Assumes the last queued transition to perform is into Resident or OnSystemRam
2. Visual hitches are unavoidable if metadata changes (e.g. new texture is of different pixel format, different number of mipmaps, resolution, etc) If that's the case, it is faster to transition to OnStorage, remove the metadata entry from cache, then to Resident again

Parameters

image	See TextureGpu::unsafeScheduleTransitionTo
autoDeleteImage	Same TextureGpu::unsafeScheduleTransitionTo
bSkipMultiload	Same TextureGpu::unsafeScheduleTransitionTo

scheduleTransitionTo()

void Ogre::TextureGpu::scheduleTransitionTo	(	GpuResidency::GpuResidency	nextResidency,
		Image2 *	image = 0,
		bool	autoDeleteImage = true,
		bool	bSkipMultiload = false
	)

Same as unsafeScheduleTransitionTo, but first checks if we're already in the residency state we want to go to, or if it has already been scheduled; thus it can be called multiple times.

setNumMipmaps()

void Ogre::TextureGpu::setNumMipmaps

(

uint8

numMipmaps

)

setOrientationMode()

virtual void Ogre::TextureGpu::setOrientationMode ( OrientationMode  orientationMode )

virtual

Sets the given orientation.

'this' must be a RenderTexture If Ogre wasn't build with OGRE_CONFIG_ENABLE_VIEWPORT_ORIENTATIONMODE, calls to this function will not stick (i.e. getOrientationMode always returns the same value)

See also

TextureGpu::msDefaultOrientationMode

TextureGpu::getInternalWidth

TextureGpu::getInternalHeight

Remarks

Must be OnStorage.

If OrientationMode == OR_DEGREE_90 or OR_DEGREE_270, the internal resolution if flipped. i.e. swap( width, height ). This is important if you need to perform copyTo operations or AsyncTextureTickets

This setting has only been tested with Vulkan and is likely to malfunction with the other APIs if set to anything other than OR_DEGREE_0

Reimplemented in Ogre::VulkanTextureGpuRenderTarget, Ogre::MetalTextureGpuRenderTarget, Ogre::GL3PlusTextureGpuRenderTarget, and Ogre::D3D11TextureGpuRenderTarget.

setPixelFormat()

void Ogre::TextureGpu::setPixelFormat

(

PixelFormatGpu

pixelFormat

)

Sets the pixel format.

Remarks

If prefersLoadingFromFileAsSRGB() returns true, the format may not be fully honoured (as we'll use the equivalent _SRGB variation).

setResolution()

void Ogre::TextureGpu::setResolution	(	uint32	width,
		uint32	height,
		uint32	depthOrSlices = 1u
	)

setSampleDescription()

void Ogre::TextureGpu::setSampleDescription

(

SampleDescription

desc

)

setTexturePoolId()

void Ogre::TextureGpu::setTexturePoolId

(

uint32

poolId

)

2D Texture with automatic batching will be merged with other textures into the same pool as one big 2D Array texture behind the scenes.

For two textures to be placed in the same pool (assuming it's not full) the following must match: Width, Height, PixelFormat, number of mipmaps, poolID

Pool ID is an arbitrary value with no actual meaning. This is ID allows you to prevent certain textures from being group together. For example, you may want all textures from Level 0 to be grouped together while Level 1 gets grouped together in a different pool

See also

TextureFlags::AutomaticBatching

TextureGpuManager::reservePoolId

Remarks

This value cannot be changed while the texture is resident (i.e. because it has already been assigned to a pool)

Parameters

poolId

Arbitrary value. Default value is 0.

setTextureType()

virtual void Ogre::TextureGpu::setTextureType ( TextureTypes::TextureTypes  textureType )

virtual

Reimplemented in Ogre::VulkanTextureGpuWindow, Ogre::VulkanTextureGpu, Ogre::MetalTextureGpuWindow, Ogre::MetalTextureGpu, Ogre::GL3PlusTextureGpuHeadlessWindow, Ogre::GL3PlusTextureGpuWindow, Ogre::GL3PlusTextureGpu, Ogre::D3D11TextureGpuWindow, and Ogre::D3D11TextureGpu.

supportsAsDepthBufferFor()

virtual bool Ogre::TextureGpu::supportsAsDepthBufferFor ( TextureGpu *  colourTarget ) const

virtual

swapBuffers()

virtual void Ogre::TextureGpu::swapBuffers ( )

inlinevirtual

Only valid for TextureGpu classes.

TODO: This may be moved to a different class.

Reimplemented in Ogre::VulkanTextureGpuWindow, Ogre::MetalTextureGpuWindow, Ogre::GL3PlusTextureGpuHeadlessWindow, Ogre::GL3PlusTextureGpuWindow, and Ogre::D3D11TextureGpuWindow.

unsafeScheduleTransitionTo()

void Ogre::TextureGpu::unsafeScheduleTransitionTo	(	GpuResidency::GpuResidency	nextResidency,
		Image2 *	image = 0,
		bool	autoDeleteImage = true,
		bool	bSkipMultiload = false
	)

Schedules an async transition in residency.

If transitioning from OnStorage to Resident, it will read from file (ResourceGroup was set in createTexture) If transitioning from OnSystemRam to Resident, it will read from the pointer it has. Multiple transitions can be stack together.

Remarks

If you're not loading from file (i.e. you're creating it programatically), call _transitionTo & _setNextResidencyStatus directly. Once you've called scheduleTransitionTo at least once, calling _transitionTo is very dangerous, as there are race conditions.

See also

TextureGpu::scheduleTransitionTo

Parameters

nextResidency	The residency to change to.
image	Pointer to image if you want to load the texture from memory instead of loading it from file or a listener. Pointer must be null if this is a manual texture. Pointer must NOT be a stack variable nor be deleted immediately. The actual loading is postponed until the request reaches the worker thread. That means the image pointer is safe to delete once you receive the TextureGpuListener::Reason::ReadyForRendering message.
autoDeleteImage	Whether we should call "delete image" once we're done using the image. Otherwise you must listen for TextureGpuListener::ReadyForRendering message to know when we're done using the image.
bSkipMultiload	Do not send this texture to be loaded by multiload (see TextureGpuManager::setMultiLoadPool) Useful if the order in which textures are being created into a pool must be preserved This value is implicitly true if image is not nullptr.

waitForData()

void Ogre::TextureGpu::waitForData

(

)

Blocks main thread until data is ready.

Afterwards isDataReady should return true. If it doesn't, then there was a problem loading the texture. See isMetadataReady remarks.

Q: What's the penalty for calling this function?

A: We need to wait for the worker thread to finish all previous textures until it processes this one. The manager only has broad resolution so it may be also possible that we even have to wait the worker thread to process a few textures that came after this one too.

Thus the cost can be anywhere from "very little" to "a lot" depending on the order in which other textures have been loaded.

The real cost is that you lose valuable ability to hide loading times. If you must call this function, you can mitigate the problem:

1. All textures you need to wait for, load them *first* together, then
   call TextureGpuManager::waitForStreamingCompletion (preferred) or
   this function. Then proceed to load the rest of the textures.
2. If you can't do the above, call this function as late as possible 

waitForMetadata()

void Ogre::TextureGpu::waitForMetadata

(

)

Blocks main thread until metadata is ready.

Afterwards isMetadataReady should return true. If it doesn't, then there was a problem loading the texture. See isMetadataReady remarks.

writeContentsToFile()

void Ogre::TextureGpu::writeContentsToFile	(	const String &	filename,
		uint8	minMip,
		uint8	maxMip,
		bool	automaticResolve = true
	)

Writes the current contents of the render target to the named file.

Member Data Documentation

msDefaultOrientationMode

OrientationMode Ogre::TextureGpu::msDefaultOrientationMode

static

PUBLIC VARIABLE.

This variable can be altered directly.

Changes are reflected immediately for new TextureGpus. Existing TextureGpus won't be affected

msFinalTextureBuffer

const IdString Ogre::TextureGpu::msFinalTextureBuffer

static

msMsaaTextureBuffer

const IdString Ogre::TextureGpu::msMsaaTextureBuffer

static

---

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

• OgreTextureGpu.h