Refactoring Axmol Rendering: RenderTexture, Camera Projection, and Explicit Offscreen Semantics

[halx99]

PR 3208 is an important step in the Axmol v3 rendering refactor. It is not just a file move or an API cleanup. It clarifies several long-standing assumptions in the rendering system:

• Is a RenderTexture size expressed in canvas coordinates or physical texture pixels?
• Should 2D rendering depend on Director's global matrix stack or the active visiting camera?
• Should offscreen rendering be controlled by RenderTexture itself or by an explicit render pass?
• Can high-DPI rendering, RenderTexture, Grid effects, ScrollView clipping, and generic VR rendering share the same coordinate model?

This PR moves the engine toward explicit rendering semantics.

RenderTexture no longer applies content scale implicitly

Previously, RenderTexture::create(width, height, ...) accepted what looked like a normal size, but internally multiplied it by AX_CONTENT_SCALE_FACTOR().

That was convenient for some legacy code, but it also made the API ambiguous. Callers could not easily tell whether they were passing a logical canvas size or a physical texture size.

After this PR:

RenderTexture::create(textureSize, ...)

means textureSize is the actual physical texture size. RenderTexture no longer silently multiplies it by the content scale factor.

If the input is in canvas coordinates and you want high-DPI density, convert it explicitly:

auto textureSize = Director::getInstance()->canvasToPixels(canvasSize);

auto rt = RenderTexture::create(textureSize,
                                PixelFormat::RGBA8,
                                PixelFormat::D24S8);

This makes the API clearer: create() creates a render target with the exact texture size you request.

This PR also provides a convenience API:

RenderTexture::createForCanvas(size, ...)

Its meaning is: the input size is measured in canvas coordinates and is converted internally using Director::canvasToPixels(). In other words, create(...) is for physical texture sizes, while createForCanvas(...) is for canvas-coordinate sizes.

RenderTexture is decoupled from 2D Node behavior

The old RenderTexture carried many responsibilities:

• It behaved like a scene node.
• It owned a sprite.
• It provided begin() and end().
• It manipulated viewport and matrix state.
• It could save images.
• It represented a GPU texture and render target.

That made it difficult to align with a modern renderer, explicit render passes, VR rendering, and multiple graphics backends.

The new direction is for RenderTexture to behave more like a texture-backed render target resource. The actual rendering process is controlled by RenderTexturePass.

The new flow is easier to reason about:

auto rt = RenderTexture::create(textureSize,
                                PixelFormat::RGBA8,
                                PixelFormat::D24S8);

auto pass = RenderTexturePass::obtain(rt);

pass->setViewport(viewport);
pass->begin();
pass->clear(ClearFlag::COLOR | ClearFlag::DEPTH, clearColor);

node->visit(renderer, transform, flags);

pass->end();
renderer->render();

RenderTexturePass is responsible for begin/end, clear, viewport, render target restore, camera override behavior, and other pass-level state. RenderTexture remains the texture resource and readback/save target.

2D rendering now uses the visiting camera view-projection

Many 2D draw paths previously read the global projection matrix:

Director::getInstance()->getMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_PROJECTION)

This made 2D rendering depend on Director's global matrix stack.

Those paths now use:

Camera::getVisitingViewProjectionMatrix()

This affects rendering components such as Sprite, Label, DrawNode, ParticleSystemQuad, AtlasNode, FastTMXLayer, and Grid rendering.

The benefit is that both 2D and 3D rendering now depend on the active visiting camera rather than a global projection matrix. This model works better for offscreen rendering, Grid effects, VR rendering, and multi-camera rendering.

Legacy matrix stack usage is removed from visit paths

Some 2D nodes used to push and pop MATRIX_STACK_MODELVIEW inside visit(). That was part of the legacy rendering compatibility layer.

This PR removes multiple instances of that pattern. Rendering now relies more directly on each node's _modelViewTransform and the current visiting camera.

The result is more local and explicit rendering state, with fewer hidden interactions between different rendering paths.

Grid rendering moves to the camera model

Grid effects previously modified Director's projection temporarily and restored it afterward. That model does not fit well with the new renderer, especially when RenderTexture, cameras, VR rendering, resizing, and resolution policies interact.

NodeGrid now uses a dedicated canvas-orthographic camera for Grid capture and rendering. Grid blit paths also use the visiting camera view-projection.

This avoids mutating global projection state and makes Grid effects compatible with the new camera-based rendering model.

Texture size APIs are clearer

This PR also replaces several older texture-size APIs:

getPixelsWide()  -> getWidth()
getPixelsHigh()  -> getHeight()
getContentSizeInPixels() -> getPixelSize()

This reduces confusion between content size and pixel size.

Under the new semantics:

• getWidth() and getHeight() mean texture pixel dimensions.
• getPixelSize() means texture pixel size.
• canvas coordinates and node content size are not treated as texture pixels.

Generic VR rendering benefits from the same model

The generic VR renderer now separates the final output size from the offscreen texture size.

Important concepts are:

• outputSize: the final distortion output viewport size.
• textureSize: the physical offscreen RenderTexture size.
• renderScale: the supersampling scale for the generic VR render texture.
• eye viewport: the region of the offscreen texture used by each eye.
• scissor transform: maps normal UI clipping into each eye viewport.

For example:

vrRenderer->setRenderScale(2.0f);

This keeps the final output size unchanged while rendering the side-by-side eye texture at a higher resolution before distortion.

This is clearer than implicitly tying VR render density to the content scale factor.

Why this matters

The core of this PR is not just an API rename. It separates concepts that used to be mixed together:

canvas coordinates
texture pixels
render view viewport
render surface size
camera view-projection
offscreen render target

Previously, these concepts were often connected through implicit conversions and global state. That was convenient in simple cases, but it made RenderTexture, Grid, VR, high-DPI rendering, resizing, and multi-backend rendering harder to maintain.

PR 3208 makes those relationships explicit and lays groundwork for the Axmol v3 rendering architecture.

Migration cost

The main migration point is RenderTexture::create().

If old code passed a canvas size and relied on internal content-scale multiplication, prefer:

auto rt = RenderTexture::createForCanvas(size,
                                         PixelFormat::RGBA8,
                                         PixelFormat::D24S8);

If you want manual conversion, use:

auto rt = RenderTexture::create(Director::getInstance()->canvasToPixels(size),
                                PixelFormat::RGBA8,
                                PixelFormat::D24S8);

If the old code already passed a physical texture size, continue using create(...) and no conversion is needed.

Custom rendering code should also migrate from Director projection matrix access to Camera::getVisitingViewProjectionMatrix().

Summary

This refactor clarifies Axmol's rendering semantics:

• RenderTexture::create() creates a render target with an explicit physical texture size.
• High-DPI conversion is performed explicitly by the caller.
• 2D rendering uses the active visiting camera.
• Grid effects no longer mutate the global projection.
• RenderTexturePass controls offscreen rendering.
• Generic VR rendering can use an explicit render scale.

Together, these changes provide a cleaner foundation for RenderTexture, camera rendering, VR, and the v3 renderer architecture.