A StagingTexture is an intermediate texture that can be read and be written from both CPU & GPU. More...

#include <OgreStagingTexture.h>

Inheritance diagram for Ogre::StagingTexture:

Public Member Functions
	StagingTexture (VaoManager *vaoManager, PixelFormatGpu formatFamily)

virtual	~StagingTexture ()

virtual size_t	_getSizeBytes ()=0
	Returns size in bytes. More...

PixelFormatGpu	getFormatFamily () const
	Returns the format family it was requested. More...

uint32	getLastFrameUsed () const

virtual bool	isSmallerThan (const StagingTexture *other) const =0

TextureBox	mapRegion (uint32 width, uint32 height, uint32 depth, uint32 slices, PixelFormatGpu pixelFormat)
	Can be called from worker thread, but not from multiple threads at the same time, also you can't call anything else either. More...

virtual void	startMapRegion ()
	Must be called from main thread when the StagingBuffer is grabbed. More...

virtual void	stopMapRegion ()
	Must be called from main thread when the StagingBuffer is released. More...

virtual bool	supportsFormat (uint32 width, uint32 height, uint32 depth, uint32 slices, PixelFormatGpu pixelFormat) const =0
	D3D11 has restrictions about which StagingTextures can be uploaded to which textures based on texture families (for example all PFG_RGBA32_* belong to the same family). More...

virtual void	upload (const TextureBox &srcBox, TextureGpu dstTexture, uint8 mipLevel, const TextureBox cpuSrcBox=0, const TextureBox *dstBox=0, bool skipSysRamCopy=false)
	Uploads a region of data in srcBox (which must have been created with mapRegion) into dstTexture. More...

bool	uploadWillStall ()
	If it returns true, startMapRegion will stall. More...

Detailed Description

A StagingTexture is an intermediate texture that can be read and be written from both CPU & GPU.

However the access in both cases is limited. GPUs can only copy (i.e. memcpy) to another real texture (can't be used directly as a texture or render target) and CPUs can only map it. In other words, a staging texture is an intermediate to transfer data between CPU & GPU

: How to write to 2 textures (texture0 & texture1; we pass twice the amount of slices to getStagingTexture): TextureGpuManager &textureManager = ...; StagingTexture *stagingTexture = textureManager.getStagingTexture( width, height, depth, slices * 2, pixelFormat ); stagingTexture->startMapRegion(); TextureBox box0 = stagingTexture->mapRegion( width, height, depth, slices, pixelFormat ); ... write to box0.data ... TextureBox box1 = stagingTexture->mapRegion( width, height, depth, slices, pixelFormat ); ... write to box1.data ... stagingTexture->stopMapRegion(); stagingTexture->upload( box0, texture0 ); stagingTexture->upload( box1, texture1 ); textureManager.removeStagingTexture( stagingTexture );

: There are other possibilities, as you can request a StagingTexture with twice the width & height and then start calling mapRegion with smaller textures and we'll handle the packing. However you have to check mapRegion doesn't return nullptr in TextureBox::data. If so, that means we have ran out of space.

Notably derived classes are:

Constructor & Destructor Documentation

◆ StagingTexture()

Ogre::StagingTexture::StagingTexture	(	VaoManager *	vaoManager,
		PixelFormatGpu	formatFamily
	)

◆ ~StagingTexture()

virtual Ogre::StagingTexture::~StagingTexture ( )

virtual

Member Function Documentation

◆ _getSizeBytes()

virtual size_t Ogre::StagingTexture::_getSizeBytes ( )

pure virtual

Returns size in bytes.

Note it's tagged as advanced use (via _underscore) because Just because a StagingTexture has enough available size, does not mean it can hold the data you'll want (a D3D11 StagingTexture of 256x512 cannot hold 1024x1 texture data even though it has the available capacity)

Returns: Size in bytes of this staging texture.

Implemented in Ogre::D3D11StagingTexture, and Ogre::StagingTextureBufferImpl.

◆ getFormatFamily()

PixelFormatGpu Ogre::StagingTexture::getFormatFamily ( ) const

inline

Returns the format family it was requested.

Note that in non-D3D11 RenderSystems, supportsFormat may return true despite a format not being from the same family. This information is mostly useful for keeping memory budgets consistent between different APIs (e.g. on D3D11 two StagingTextures, one that supports RGB8, another for BC1 of 64 MB each; on OpenGL we need to request two textures of 64MB each, and not just one because the first one can fulfill every request)

◆ getLastFrameUsed()

uint32 Ogre::StagingTexture::getLastFrameUsed ( ) const

inline

◆ isSmallerThan()

virtual bool Ogre::StagingTexture::isSmallerThan ( const StagingTexture * other ) const

pure virtual

Implemented in Ogre::D3D11StagingTexture, and Ogre::StagingTextureBufferImpl.

◆ mapRegion()

TextureBox Ogre::StagingTexture::mapRegion	(	uint32	width,
		uint32	height,
		uint32	depth,
		uint32	slices,
		PixelFormatGpu	pixelFormat
	)

Can be called from worker thread, but not from multiple threads at the same time, also you can't call anything else either.

Remarks: You must have called startMapRegion before. Textures that are bigger than 2048x2048 can only map one slice at a time due to limitations in the D3D11 API.

Returns: TextureBox to write to. Please note TextureBox::data may be null. If so, that means we don't have enough space to fulfill your request.

You MUST use TextureBox::atFromOffsettedOrigin rather than TextureBox::at (or account for the offset at some point)

Most APIs will return the value starting at 0 0 0 But D3D11 will NOT.

◆ startMapRegion()

virtual void Ogre::StagingTexture::startMapRegion ( )

virtual

Must be called from main thread when the StagingBuffer is grabbed.

Remarks: Calling this function if you've already called upload() may stall. Grab another StagingTexture to prevent stall. See uploadWillStall.

Reimplemented in Ogre::VulkanStagingTexture, Ogre::GL3PlusStagingTexture, Ogre::D3D11StagingTexture, and Ogre::StagingTextureBufferImpl.

◆ stopMapRegion()

virtual void Ogre::StagingTexture::stopMapRegion ( )

virtual

Must be called from main thread when the StagingBuffer is released.

Reimplemented in Ogre::VulkanStagingTexture, Ogre::MetalStagingTexture, Ogre::GL3PlusStagingTexture, and Ogre::D3D11StagingTexture.

◆ supportsFormat()

virtual bool Ogre::StagingTexture::supportsFormat	(	uint32	width,
		uint32	height,
		uint32	depth,
		uint32	slices,
		PixelFormatGpu	pixelFormat
	)		const

pure virtual

D3D11 has restrictions about which StagingTextures can be uploaded to which textures based on texture families (for example all PFG_RGBA32_* belong to the same family).

This function will return true if the StagingTexture can be used with the given format. On all the other RenderSystems, this nonsense does not exist thus it returns always true unless the request is so big it could never be fullfilled (it's larger than our maximum capacity)

Implemented in Ogre::VulkanStagingTexture, Ogre::D3D11StagingTexture, and Ogre::StagingTextureBufferImpl.

◆ upload()

virtual void Ogre::StagingTexture::upload	(	const TextureBox &	srcBox,
		TextureGpu *	dstTexture,
		uint8	mipLevel,
		const TextureBox *	cpuSrcBox = `0`,
		const TextureBox *	dstBox = `0`,
		bool	skipSysRamCopy = `false`
	)

virtual

Uploads a region of data in srcBox (which must have been created with mapRegion) into dstTexture.

Parameters

srcBox	The source data to copy from. Must have been created from mapRegion and must not have been altered (i.e. changed its internal variables) Values inside srcBox such as x, y, z & sliceStart will be ignored.
dstTexture	The destination texture. If dstBox is a null pointer, srcBox must match the texture dimensions exactly (x,y,z = 0; same resolution)
cpuSrcBox	A CPU-based copy that we can copy CPU -> CPU to our System RAM copy. This parameters must be present if skipSysRamCopy is false and the dstTexture strategy is GpuPageOutStrategy::AlwaysKeepSystemRamCopy or it is in OnSystemRam state.
mipLevel	Destination mipmap.
dstBox	Optional. Region inside dstTexture to copy to. Must have the same dimensions as srcBox. Values inside dstBox such as bytesPerRow, bytesPerImage & data will be ignored.
skipSysRamCopy	Whether to skip the copy to system RAM. Should only be used if the System RAM copy is already up to date, which is often the case when you're transitioning to Resident while loading at the same time. If misused, readbacks will be incorrect as data in CPU won't mirror that of the data in GPU, and possibly other bugs too.

Reimplemented in Ogre::VulkanStagingTexture, Ogre::MetalStagingTexture, Ogre::GL3PlusStagingTexture, and Ogre::D3D11StagingTexture.

◆ uploadWillStall()

bool Ogre::StagingTexture::uploadWillStall ( )

If it returns true, startMapRegion will stall.

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

OgreStagingTexture.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ StagingTexture()

◆ ~StagingTexture()

Member Function Documentation

◆ _getSizeBytes()

◆ getFormatFamily()

◆ getLastFrameUsed()

◆ isSmallerThan()

◆ mapRegion()

◆ startMapRegion()

◆ stopMapRegion()

◆ supportsFormat()

◆ upload()

◆ uploadWillStall()