Skip to main content
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);

​
See Also

  • View - Associate render target with a view
  • Texture - Create textures for attachments
  • Engine - Create and destroy render targets

Build docs developers (and LLMs) love

Get started for freeTalk to us