RenderTexturePass Class Reference

Manages an offscreen render pass into a RenderTexture. More...

#include <RenderTexturePass.h>

Inherits Object.

Public Member Functions
void	setCameraOverrideEnabled (bool enabled)
	Enables or disables automatic camera adjustment for this pass.
bool	isCameraOverrideEnabled () const
	Returns whether this pass automatically overrides the visiting camera.
Target
void	setTarget (RenderTexture *rt)
Viewport
void	setViewport (std::optional< Viewport > vp)
Viewport	makeVirtualViewport (const Vec2 &rtBegin, const Rect &fullRect, const Rect &fullViewport) const
	Computes a virtual viewport rectangle for rendering into a RenderTexture.
Lifecycle
void	begin (const Camera *camera=nullptr)
	Begin offscreen rendering.
void	end ()
	End offscreen rendering.
Clear (must be called between begin() / end())
void	clear (ClearFlag flags, const ClearValue &value=ClearValue{})
	Clear the active render target.
void	clearColor (const Color &color)
	Clear color buffer only.
void	clearDepth (float depth)
	Clear depth buffer only.
void	clearStencil (unsigned int stencil)
	Clear stencil buffer only.
void	clearAll (const ClearValue &value=ClearValue{})
	Clear all buffers (color|depth|stencil).
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 RenderTexturePass *	obtain (RenderTexture *rt=nullptr)
	Obtain a new render texture pass instance (ref count 1, does not enter autorelease pool).

Detailed Description

Manages an offscreen render pass into a RenderTexture.

RenderTexturePass is a lightweight helper that brackets a group of renderer commands between begin() and end(). Commands submitted while the pass is active are recorded into a dedicated renderer group. When that group is executed, the pass saves the current render target and viewport, binds the RenderTexture's render target, optionally applies a custom viewport, and restores the previous state at the end of the group.

This class is intentionally not a render target resource. It does not own the RenderTexture, does not traverse a scene by itself, and does not flush the renderer automatically. Callers are responsible for submitting draw commands between begin() and end(), then flushing the renderer at an appropriate time.

ordering

Axmol's renderer does not execute commands strictly in submission order. Render queues are sorted by type and global order; in particular, 3D commands may be processed before regular GLOBALZ_ZERO commands. For this reason, the internal begin callback must be scheduled with an early global order, and the internal end callback must be scheduled with a late global order. This guarantees that all commands submitted between begin() and end(), including 3D, 2D, debug draw, and custom commands, are executed while the RenderTexture is bound.

The clear() helpers are also scheduled after the render target has been bound and before normal draw commands, so they clear the intended RenderTexture rather than the previously active render target.

consistency across graphics backends

On OpenGL, offscreen FBO textures have a bottom-left origin, while D3D, Metal, and Vulkan use a top-left origin. When automatic Y flipping is enabled, this pass can flip the selected camera's projection matrix on OpenGL so that the rendered texture has a consistent orientation across backends.

Note

This guarantee applies only to rendering managed by RenderTexturePass. If you access RenderTexture::getRenderTarget() directly and manage the rendering pipeline yourself, you must handle backend-specific Y-axis orientation yourself.

Usage

auto rt = RenderTexture::create(w, h);
auto pass = RefPtr<RenderTexturePass>(RenderTexturePass::obtain(rt), tlx::adopt_object);
 
pass->begin(camera);
pass->clear(ClearFlag::COLOR | ClearFlag::DEPTH_AND_STENCIL,
            {.color = Color(0, 0, 0, 1)});
// Submit draw commands here.
pass->end();
 
renderer->render();

Use a separate RenderTexturePass object for nested render target passes.

Member Function Documentation

obtain()

RenderTexturePass * obtain ( RenderTexture * rt = nullptr )

static

Obtain a new render texture pass instance (ref count 1, does not enter autorelease pool).

Parameters

rt	Optional render texture to assign. If null, call setTarget() before begin().

Returns

A RenderTexturePass* with reference count 1. Call release() when done, or wrap in RefPtr<T>(ptr, tlx::adopt_object) for automatic management.

setTarget()

void setTarget

(

RenderTexture *

rt

)

Set render target. Must be called before begin(), not while active.

setViewport()

void setViewport

(

std::optional< Viewport >

vp

)

Set custom viewport. Must be called before begin().

makeVirtualViewport()

Viewport makeVirtualViewport	(	const Vec2 &	rtBegin,
		const Rect &	fullRect,
		const Rect &	fullViewport ) const

Computes a virtual viewport rectangle for rendering into a RenderTexture.

This function maps a sub-rectangle of the full render target (fullRect) into the coordinate space of the specified full viewport (fullViewport), relative to the RenderTexture begin offset (rtBegin). It produces a Viewport object that can be used for scissor or rendering operations inside the RenderTexture.

Parameters

rtBegin	The origin offset (x, y) of the RenderTexture region where rendering begins.
fullRect	The full rectangle of the RenderTexture in local coordinates.
fullViewport	The full viewport rectangle in local coordinates.

Returns

A Viewport structure containing the computed x/y position and width/height of the virtual viewport. If any input rectangle has non-positive dimensions, an empty Viewport is returned.

Note

The calculation scales the rectangle coordinates by the ratio of fullViewport.size to fullRect.size, ensuring that the resulting viewport aligns correctly with the RenderTexture’s coordinate system.

begin()

void begin

(

const Camera *

camera = nullptr

)

Begin offscreen rendering.

Parameters

camera

Optional camera used for backend-specific projection adjustment. Saves current render target/viewport, pushes render group.

end()

void end

(

)

End offscreen rendering.

Restores previous render target/viewport and camera projection.

clear()

void clear	(	ClearFlag	flags,
		const ClearValue &	value = ClearValue{} )

Clear the active render target.

Parameters

flags	Bitmask of ClearFlag (COLOR|DEPTH|STENCIL).
value	Clear parameters (color, depth, stencil).

Precondition

Must be called between begin() and end().

clearColor()

void clearColor ( const Color & color )

inline

Clear color buffer only.

Precondition

begin() .. end()

clearDepth()

void clearDepth ( float depth )

inline

Clear depth buffer only.

Precondition

begin() .. end()

clearStencil()

void clearStencil ( unsigned int stencil )

inline

Clear stencil buffer only.

Precondition

begin() .. end()

clearAll()

void clearAll ( const ClearValue & value = ClearValue{} )

inline

Clear all buffers (color|depth|stencil).

Precondition

begin() .. end()

setCameraOverrideEnabled()

void setCameraOverrideEnabled ( bool enabled )

inline

Enables or disables automatic camera adjustment for this pass.

When enabled, begin() applies backend-specific projection adjustments to the selected camera when needed. end() restores the projection state.

Advanced renderers that manage their own camera loop, such as VR or custom multi-view renderers, can disable this behavior and handle camera state explicitly.

Parameters

enabled

True to let RenderTexturePass adjust the selected camera; false to leave camera projection untouched.

---

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

• RenderTexturePass.h