RenderTarget

An offscreen render target that can be associated with a View and contains weak references to a set of attached Texture objects.

Overview

RenderTarget is intended to be used with the View’s post-processing disabled for the most part, especially when a DEPTH attachment is also used. Custom RenderTargets are ultimately intended to render into textures that might be used during the main render pass.

Clients are responsible for the lifetime of all associated Texture attachments.

Creation and Usage

A RenderTarget is created using the RenderTarget::Builder and destroyed by calling Engine::destroy(const RenderTarget*).

filament::Engine* engine = filament::Engine::create();
filament::Texture* colorTexture = filament::Texture::Builder()
    .width(1024)
    .height(1024)
    .format(filament::Texture::InternalFormat::RGBA8)
    .usage(filament::Texture::Usage::COLOR_ATTACHMENT | 
           filament::Texture::Usage::SAMPLEABLE)
    .build(*engine);

filament::RenderTarget* renderTarget = filament::RenderTarget::Builder()
    .texture(filament::RenderTarget::AttachmentPoint::COLOR, colorTexture)
    .build(*engine);

myView->setRenderTarget(renderTarget);

// Later...
engine->destroy(renderTarget);
engine->destroy(colorTexture);

Constants

MIN_SUPPORTED_COLOR_ATTACHMENTS_COUNT

Minimum number of color attachments supported.

MAX_SUPPORTED_COLOR_ATTACHMENTS_COUNT

Maximum number of color attachments supported.

Enumerations

AttachmentPoint

Identifies attachment points for textures.

enum class AttachmentPoint : uint8_t {
    COLOR0 = 0,  // or COLOR
    COLOR1 = 1,
    COLOR2 = 2,
    COLOR3 = 3,
    COLOR4 = 4,
    COLOR5 = 5,
    COLOR6 = 6,
    COLOR7 = 7,
    DEPTH  = MAX_SUPPORTED_COLOR_ATTACHMENTS_COUNT
};

COLOR0 through COLOR7 - Color attachment points (COLOR0 is aliased as COLOR)
DEPTH - Depth attachment point

CubemapFace

Alias for backend::TextureCubemapFace, used to specify which face of a cubemap to render to.

Builder Methods

texture()

Builder& texture(AttachmentPoint attachment, Texture* texture) noexcept;

Sets a texture to a given attachment point. Important notes for DEPTH attachments:

Always disable post-processing in the View when using a DEPTH attachment
Set Usage::SAMPLEABLE on the DEPTH attachment if you need to preserve its content after rendering
Without SAMPLEABLE, the DEPTH buffer content may be discarded

Parameters:

attachment - The attachment point of the texture
texture - The associated texture object (or nullptr to clear)

Returns: Reference to this Builder for chaining calls Example:

filament::Texture* depthTexture = filament::Texture::Builder()
    .width(1024)
    .height(1024)
    .format(filament::Texture::InternalFormat::DEPTH24)
    .usage(filament::Texture::Usage::DEPTH_ATTACHMENT | 
           filament::Texture::Usage::SAMPLEABLE)
    .build(*engine);

filament::RenderTarget::Builder()
    .texture(AttachmentPoint::COLOR, colorTexture)
    .texture(AttachmentPoint::DEPTH, depthTexture)
    .build(*engine);

mipLevel()

Builder& mipLevel(AttachmentPoint attachment, uint8_t level) noexcept;

Sets the mipmap level for a given attachment point. Parameters:

attachment - The attachment point
level - The mipmap level (default: 0)

Returns: Reference to this Builder for chaining calls Example:

RenderTarget::Builder()
    .texture(AttachmentPoint::COLOR, colorTexture)
    .mipLevel(AttachmentPoint::COLOR, 2)  // Render to mip level 2
    .build(*engine);

face()

Builder& face(AttachmentPoint attachment, CubemapFace face) noexcept;

Sets the face for cubemap textures at the given attachment point. Parameters:

attachment - The attachment point
face - The cubemap face to render to

Returns: Reference to this Builder for chaining calls Example:

RenderTarget::Builder()
    .texture(AttachmentPoint::COLOR, cubemapTexture)
    .face(AttachmentPoint::COLOR, CubemapFace::POSITIVE_X)
    .build(*engine);

layer()

Builder& layer(AttachmentPoint attachment, uint32_t layer) noexcept;

Sets an index of a single layer for 2D array, cubemap array, and 3D textures. For cubemap array textures, the layer is translated into:

Array index: layer / 6
Face: layer % 6

Parameters:

attachment - The attachment point
layer - The layer index

Returns: Reference to this Builder for chaining calls Example:

RenderTarget::Builder()
    .texture(AttachmentPoint::COLOR, arrayTexture)
    .layer(AttachmentPoint::COLOR, 3)  // Render to layer 3
    .build(*engine);

multiview()

Builder& multiview(AttachmentPoint attachment, 
                  uint8_t layerCount, 
                  uint8_t baseLayer = 0) noexcept;

Sets the starting index of 2D array textures for multiview rendering.

This requires COLOR and DEPTH attachments (if set) to be 2D array textures.

Parameters:

attachment - The attachment point
layerCount - The number of layers used for multiview, starting from baseLayer
baseLayer - The starting index of the 2D array texture (default: 0)

Returns: Reference to this Builder for chaining calls Example:

RenderTarget::Builder()
    .texture(AttachmentPoint::COLOR, arrayTexture)
    .multiview(AttachmentPoint::COLOR, 2, 0)  // 2 views starting at layer 0
    .build(*engine);

samples()

Builder& samples(uint8_t samples) noexcept;

Sets the number of samples used for MSAA (Multisample Anti-Aliasing). Parameters:

samples - The number of samples for multisampling

Returns: Reference to this Builder for chaining calls Example:

RenderTarget::Builder()
    .texture(AttachmentPoint::COLOR, colorTexture)
    .samples(4)  // 4x MSAA
    .build(*engine);

build()

RenderTarget* build(Engine& engine);

Creates the RenderTarget object and returns a pointer to it. Parameters:

engine - Reference to the Filament Engine

Returns: Pointer to the newly created RenderTarget

Instance Methods

getTexture()

Texture* getTexture(AttachmentPoint attachment) const noexcept;

Gets the texture set on the given attachment point. Parameters:

attachment - Attachment point to query

Returns: A Texture object or nullptr if no texture is set

getMipLevel()

uint8_t getMipLevel(AttachmentPoint attachment) const noexcept;

Returns the mipmap level set on the given attachment point. Parameters:

attachment - Attachment point to query

Returns: The mipmap level

getFace()

CubemapFace getFace(AttachmentPoint attachment) const noexcept;

Returns the face of a cubemap set on the given attachment point. Parameters:

attachment - Attachment point to query

Returns: A cubemap face identifier (only relevant if the attachment’s texture is a cubemap)

getLayer()

uint32_t getLayer(AttachmentPoint attachment) const noexcept;

Returns the texture layer set on the given attachment point. Parameters:

attachment - Attachment point to query

Returns: A texture layer (only relevant if the attachment’s texture is a 3D texture)

getSupportedColorAttachmentsCount()

uint8_t getSupportedColorAttachmentsCount() const noexcept;

Returns the number of color attachments usable by this Engine instance. Guaranteed to return at least MIN_SUPPORTED_COLOR_ATTACHMENTS_COUNT and at most MAX_SUPPORTED_COLOR_ATTACHMENTS_COUNT. Returns: Number of color attachments usable in a render target

Complete Example

Here’s a complete example of creating a render target with both color and depth attachments:

#include <filament/Engine.h>
#include <filament/Texture.h>
#include <filament/RenderTarget.h>
#include <filament/View.h>

filament::Engine* engine = filament::Engine::create();

// Create color texture
filament::Texture* colorTexture = filament::Texture::Builder()
    .width(1920)
    .height(1080)
    .format(filament::Texture::InternalFormat::RGBA16F)
    .usage(filament::Texture::Usage::COLOR_ATTACHMENT | 
           filament::Texture::Usage::SAMPLEABLE)
    .build(*engine);

// Create depth texture
filament::Texture* depthTexture = filament::Texture::Builder()
    .width(1920)
    .height(1080)
    .format(filament::Texture::InternalFormat::DEPTH24)
    .usage(filament::Texture::Usage::DEPTH_ATTACHMENT | 
           filament::Texture::Usage::SAMPLEABLE)
    .build(*engine);

// Create render target
filament::RenderTarget* renderTarget = filament::RenderTarget::Builder()
    .texture(filament::RenderTarget::AttachmentPoint::COLOR, colorTexture)
    .texture(filament::RenderTarget::AttachmentPoint::DEPTH, depthTexture)
    .build(*engine);

// Set on view and disable post-processing
filament::View* view = engine->createView();
view->setRenderTarget(renderTarget);
view->setPostProcessingEnabled(false);

// Cleanup
engine->destroy(renderTarget);
engine->destroy(colorTexture);
engine->destroy(depthTexture);
engine->destroy(view);

Core Classes

Materials & Rendering

Lighting & Camera

Transform & Animation

Utilities

Overview

Creation and Usage

Constants

MIN_SUPPORTED_COLOR_ATTACHMENTS_COUNT

MAX_SUPPORTED_COLOR_ATTACHMENTS_COUNT

Enumerations

AttachmentPoint

CubemapFace

Builder Methods

texture()

mipLevel()

face()

layer()

multiview()

samples()

build()

Instance Methods

getTexture()

getMipLevel()

getFace()

getLayer()

getSupportedColorAttachmentsCount()

Complete Example

See Also

Build docs developers (and LLMs) love

Core Classes

Materials & Rendering

Lighting & Camera

Transform & Animation

Utilities

​Overview

​Creation and Usage

​Constants

​MIN_SUPPORTED_COLOR_ATTACHMENTS_COUNT

​MAX_SUPPORTED_COLOR_ATTACHMENTS_COUNT

​Enumerations

​AttachmentPoint

​CubemapFace

​Builder Methods

​texture()

​mipLevel()

​face()

​layer()

​multiview()

​samples()

​build()

​Instance Methods

​getTexture()

​getMipLevel()

​getFace()

​getLayer()

​getSupportedColorAttachmentsCount()

​Complete Example

​See Also

Build docs developers (and LLMs) love

Overview

Creation and Usage

Constants

MIN_SUPPORTED_COLOR_ATTACHMENTS_COUNT

MAX_SUPPORTED_COLOR_ATTACHMENTS_COUNT

Enumerations

AttachmentPoint

CubemapFace

Builder Methods

texture()

mipLevel()

face()

layer()

multiview()

samples()

build()

Instance Methods

getTexture()

getMipLevel()

getFace()

getLayer()

getSupportedColorAttachmentsCount()

Complete Example

See Also