RenderTexture is a render target resource, inheriting from Texture2D. More...

#include <RenderTexture.h>

Public Types
using	SaveFileCallbackType = std::function<void(RenderTexture*, std::string_view)>
	Callback invoked after an asynchronous save-to-file request completes.
Public Types inherited from Texture2D
using	TexParams = rhi::SamplerDesc
	Extension to set the Min / Mag filter.

Public Member Functions
rhi::RenderTarget *	getRenderTarget () const
	Returns the underlying render target used for offscreen rendering.
Texture2D *	getDepthStencilTexture () const
	Returns the optional depth/stencil texture attached to this render texture.
rhi::PixelFormat	getDepthStencilFormat () const
	Returns the depth/stencil attachment format.
Vec2	getRenderSize () const
	Returns the render target size in pixels.
void	newImage (std::function< void(RefPtr< Image >)> imageCallback)
	Reads the render texture pixels into an Image asynchronously.
bool	saveToFile (std::string_view filename, bool isRGBA=true, SaveFileCallbackType callback=nullptr)
	Saves the render texture to a file using the filename extension to infer the format.
bool	saveToFile (std::string_view fileName, Image::Format format, bool isRGBA=true, SaveFileCallbackType callback=nullptr)
	Saves the render texture to a file using an explicit image format.
bool	saveToFileAsNonPMA (std::string_view filename, bool isRGBA=true, SaveFileCallbackType callback=nullptr)
	Saves the render texture to a file after converting pixels from premultiplied alpha.
bool	saveToFileAsNonPMA (std::string_view fileName, Image::Format format, bool isRGBA, SaveFileCallbackType callback)
	Saves the render texture to a file using an explicit format after converting pixels from premultiplied alpha.
Public Member Functions inherited from Texture2D
virtual	~Texture2D ()
	@lua NA
bool	initWithImage (Image *image, PixelFormat renderFormat=PixelFormat::NONE, bool autoGenMipmaps=false)
	Initializes a texture from a Image object.
bool	initWithString (std::string_view text, std::string_view fontName, float fontSize, const Vec2 &dimensions=Vec2(0, 0), TextHAlignment hAlignment=TextHAlignment::CENTER, TextVAlignment vAlignment=TextVAlignment::TOP, bool enableWrap=true, int overflow=0)
	Initializes a texture from a string with dimensions, alignment, font name and font size.
bool	initWithString (std::string_view text, const FontDefinition &textDefinition)
	Initializes a texture from a string using a text definition.
bool	initWithData (const void *data, ssize_t dataSize, rhi::PixelFormat pixelFormat, int pixelsWide, int pixelsHigh, bool preMultipliedAlpha=false, bool autoGenMipmaps=false)
	Initializes with a texture2d with data.
bool	initWithData (const void *data, ssize_t dataSize, rhi::PixelFormat pixelFormat, rhi::PixelFormat renderFormat, int pixelsWide, int pixelsHigh, bool preMultipliedAlpha=false, bool autoGenMipmaps=false)
	Initializes with a texture2d with data.
bool	initWithMipmaps (std::span< MipmapInfo > mipmaps, rhi::PixelFormat pixelFormat, rhi::PixelFormat renderFormat, int pixelsWide, int pixelsHigh, bool preMultipliedAlpha=false)
	Initializes with mipmaps.
bool	updateData (Image *image)
	update data by image
bool	updateData (std::span< const TextureSliceData > subDatas)
	update data by subDatas
bool	updateData (const void *data, int width, int height, int level=0, int layerIndex=0)
	Update the texture with a new image data.
bool	updateSubData (const void *data, int offsetX, int offsetY, int width, int height, int level=0, int layerIndex=0)
	Update texture sub data.
int	getWidth () const
	Returns the texture width in physical pixels.
int	getHeight () const
	Returns the texture height in physical pixels.
Vec2	getPixelSize () const
	Returns the physical pixel size of the texture as a float vector.
Vec2	getContentSize () const
	Returns the logical content size of the texture in points.
float	getMaxS () const
	Gets max S.
void	setMaxS (float maxS)
	Sets max S.
float	getMaxT () const
	Gets max T.
void	setMaxT (float maxT)
	Sets max T.
void	setAntiAliasTexParameters ()
	Sets antialias texture parameters:
void	setAliasTexParameters ()
	Sets alias texture parameters:
const char *	getStringForFormat () const
	Returns the pixel format.
unsigned int	getBitsPerPixelForFormat () const
	Returns the bits-per-pixel of the in-memory OpenGL texture.
unsigned int	getBitsPerPixelForFormat (rhi::PixelFormat format) const
	Helper functions that returns bits per pixels for a given format.
bool	hasPremultipliedAlpha () const
	Whether or not the texture has their Alpha premultiplied.
bool	hasMipmaps () const
	Whether or not the texture has mip maps.
rhi::PixelFormat	getPixelFormat () const
	Gets the pixel format of the texture.
Public Member Functions inherited from Object
void	retain ()
	Retains the ownership.
void	release ()
	Releases the ownership immediately.
Object *	autorelease ()
	Releases the ownership sometime soon automatically.
unsigned int	getReferenceCount () const
	Returns the Object's current reference count.
uint64_t	getObjectID () const noexcept
	Returns the process-local diagnostic identifier assigned at construction.
virtual	~Object ()
	Destructor.

Static Public Member Functions
static RenderTexture *	create (int w, int h, rhi::PixelFormat format=rhi::PixelFormat::RGBA8, rhi::PixelFormat depthStencilFormat=rhi::PixelFormat::NONE)
	Creates a render texture with an optional depth/stencil attachment.
static RenderTexture *	createForCanvas (const Vec2 &contentSize, rhi::PixelFormat format=rhi::PixelFormat::RGBA8, rhi::PixelFormat depthStencilFormat=rhi::PixelFormat::NONE)
	Creates a render texture for content measured in canvas coordinates.

Detailed Description

RenderTexture is a render target resource, inheriting from Texture2D.

It holds the GPU resources (color texture, optional depth/stencil texture, render target binding) needed for offscreen rendering.

To render into a RenderTexture, use RenderTexturePass:

auto rt = RenderTexture::create(w, h);
auto pass = RefPtr<RenderTexturePass>(RenderTexturePass::obtain(rt), tlx::adopt_object);
pass->begin();
// ... render content ...
pass->end();

consistency across graphics backends

On OpenGL, offscreen FBO textures have a bottom-left origin, while Direct3D, Metal, and Vulkan use a top-left origin. By default (_autoFlipY == true), RenderTexturePass automatically flips the visiting camera's projection matrix on OpenGL so that the rendered texture has a consistent top-left origin across all platforms.

If you access getRenderTarget() directly and manage the rendering pipeline yourself (e.g., Live2D CubismRenderer), you must check rhi::GraphicsCore::isOpenGL() and flip the Y-axis manually.

If you render through RenderTexturePass, call RenderTexturePass::setAutoFlipY(false) to preserve the raw backend-native orientation. This is useful when the texture will be consumed by a system that expects the native coordinate system, such as VR/OpenXR compositors.

Member Function Documentation

◆ create()

RenderTexture * create	(	int	w,
		int	h,
		rhi::PixelFormat	format = rhi::PixelFormat::RGBA8,
		rhi::PixelFormat	depthStencilFormat = rhi::PixelFormat::NONE )

static

Creates a render texture with an optional depth/stencil attachment.

Parameters

w	Width in pixels.
h	Height in pixels.
format	Color texture pixel format.
depthStencilFormat	Depth/stencil texture format, or NONE if not needed.

Returns: A new autoreleased RenderTexture instance, or nullptr on failure.

◆ createForCanvas()

RenderTexture * createForCanvas	(	const Vec2 &	contentSize,
		rhi::PixelFormat	format = rhi::PixelFormat::RGBA8,
		rhi::PixelFormat	depthStencilFormat = rhi::PixelFormat::NONE )

static

Creates a render texture for content measured in canvas coordinates.

The input size is interpreted in canvas coordinates and converted to physical texture pixels using Director::canvasToPixels(). Use create() when the size is already in texture pixels.

◆ getRenderSize()

Vec2 getRenderSize ( ) const

inline

Returns the render target size in pixels.

This is a render-target semantic alias of Texture2D::getPixelSize().

◆ newImage()

void newImage ( std::function< void(RefPtr< Image >)> imageCallback )

Reads the render texture pixels into an Image asynchronously.

Parameters

imageCallback Callback receiving the captured image.

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

RenderTexture.h

Public Types

Public Member Functions