impeller::RenderTarget Class Reference

#include <render_target.h>

Classes
struct	AttachmentConfig
struct	AttachmentConfigMSAA

Public Member Functions
	RenderTarget ()
	~RenderTarget ()
bool	IsValid () const
void	SetupStencilAttachment (const Context &context, RenderTargetAllocator &allocator, ISize size, bool msaa, const std::string &label="Offscreen", AttachmentConfig stencil_attachment_config=kDefaultStencilAttachmentConfig)
SampleCount	GetSampleCount () const
bool	HasColorAttachment (size_t index) const
ISize	GetRenderTargetSize () const
std::shared_ptr< Texture >	GetRenderTargetTexture () const
PixelFormat	GetRenderTargetPixelFormat () const
std::optional< ISize >	GetColorAttachmentSize (size_t index) const
RenderTarget &	SetColorAttachment (const ColorAttachment &attachment, size_t index)
RenderTarget &	SetDepthAttachment (std::optional< DepthAttachment > attachment)
RenderTarget &	SetStencilAttachment (std::optional< StencilAttachment > attachment)
size_t	GetMaxColorAttacmentBindIndex () const
const std::map< size_t, ColorAttachment > &	GetColorAttachments () const
const std::optional< DepthAttachment > &	GetDepthAttachment () const
const std::optional< StencilAttachment > &	GetStencilAttachment () const
size_t	GetTotalAttachmentCount () const
void	IterateAllAttachments (const std::function< bool(const Attachment &attachment)> &iterator) const
std::string	ToString () const

Static Public Member Functions
static RenderTarget	CreateOffscreen (const Context &context, RenderTargetAllocator &allocator, ISize size, const std::string &label="Offscreen", AttachmentConfig color_attachment_config=kDefaultColorAttachmentConfig, std::optional< AttachmentConfig > stencil_attachment_config=kDefaultStencilAttachmentConfig)
static RenderTarget	CreateOffscreenMSAA (const Context &context, RenderTargetAllocator &allocator, ISize size, const std::string &label="Offscreen MSAA", AttachmentConfigMSAA color_attachment_config=kDefaultColorAttachmentConfigMSAA, std::optional< AttachmentConfig > stencil_attachment_config=kDefaultStencilAttachmentConfig)

Static Public Attributes
static constexpr AttachmentConfig	kDefaultColorAttachmentConfig
static constexpr AttachmentConfigMSAA	kDefaultColorAttachmentConfigMSAA
static constexpr AttachmentConfig	kDefaultStencilAttachmentConfig

Detailed Description

Definition at line 49 of file render_target.h.

Constructor & Destructor Documentation

RenderTarget()

impeller::RenderTarget::RenderTarget ( )

default

~RenderTarget()

impeller::RenderTarget::~RenderTarget ( )

default

Member Function Documentation

CreateOffscreen()

RenderTarget impeller::RenderTarget::CreateOffscreen ( const Context &  context, RenderTargetAllocator &  allocator, ISize  size, const std::string &  label = "Offscreen", AttachmentConfig  color_attachment_config = kDefaultColorAttachmentConfig, std::optional< AttachmentConfig >  stencil_attachment_config = kDefaultStencilAttachmentConfig  )

static

Definition at line 223 of file render_target.cc.

                                                             {
  if (size.IsEmpty()) {
    return {};
  }
 
  RenderTarget target;
  PixelFormat pixel_format = context.GetCapabilities()->GetDefaultColorFormat();
  TextureDescriptor color_tex0;
  color_tex0.storage_mode = color_attachment_config.storage_mode;
  color_tex0.format = pixel_format;
  color_tex0.size = size;
  color_tex0.usage = static_cast<uint64_t>(TextureUsage::kRenderTarget) |
                     static_cast<uint64_t>(TextureUsage::kShaderRead);
 
  ColorAttachment color0;
  color0.clear_color = color_attachment_config.clear_color;
  color0.load_action = color_attachment_config.load_action;
  color0.store_action = color_attachment_config.store_action;
  color0.texture = allocator.CreateTexture(color_tex0);
 
  if (!color0.texture) {
    return {};
  }
  color0.texture->SetLabel(SPrintF("%s Color Texture", label.c_str()));
  target.SetColorAttachment(color0, 0u);
 
  if (stencil_attachment_config.has_value()) {
    target.SetupStencilAttachment(context, allocator, size, false, label,
                                  stencil_attachment_config.value());
  } else {
    target.SetStencilAttachment(std::nullopt);
  }
 
  return target;
}

References impeller::RenderTarget::AttachmentConfig::clear_color, impeller::ColorAttachment::clear_color, impeller::RenderTargetAllocator::CreateTexture(), impeller::TextureDescriptor::format, impeller::Context::GetCapabilities(), impeller::TSize< T >::IsEmpty(), impeller::kRenderTarget, impeller::kShaderRead, impeller::RenderTarget::AttachmentConfig::load_action, impeller::Attachment::load_action, SetColorAttachment(), SetStencilAttachment(), SetupStencilAttachment(), impeller::TextureDescriptor::size, impeller::SPrintF(), impeller::TextureDescriptor::storage_mode, impeller::RenderTarget::AttachmentConfig::storage_mode, impeller::RenderTarget::AttachmentConfig::store_action, impeller::Attachment::store_action, impeller::Attachment::texture, and impeller::TextureDescriptor::usage.

Referenced by impeller::CreateRenderTarget(), impeller::ContentContext::MakeSubpass(), impeller::SceneContents::Render(), and impeller::testing::TEST_P().

CreateOffscreenMSAA()

RenderTarget impeller::RenderTarget::CreateOffscreenMSAA ( const Context &  context, RenderTargetAllocator &  allocator, ISize  size, const std::string &  label = "Offscreen MSAA", AttachmentConfigMSAA  color_attachment_config = kDefaultColorAttachmentConfigMSAA, std::optional< AttachmentConfig >  stencil_attachment_config = kDefaultStencilAttachmentConfig  )

static

Definition at line 265 of file render_target.cc.

                                                             {
  if (size.IsEmpty()) {
    return {};
  }
 
  RenderTarget target;
  PixelFormat pixel_format = context.GetCapabilities()->GetDefaultColorFormat();
 
  // Create MSAA color texture.
 
  TextureDescriptor color0_tex_desc;
  color0_tex_desc.storage_mode = color_attachment_config.storage_mode;
  color0_tex_desc.type = TextureType::kTexture2DMultisample;
  color0_tex_desc.sample_count = SampleCount::kCount4;
  color0_tex_desc.format = pixel_format;
  color0_tex_desc.size = size;
  color0_tex_desc.usage = static_cast<uint64_t>(TextureUsage::kRenderTarget);
 
  if (context.GetCapabilities()->SupportsImplicitResolvingMSAA()) {
    // See below ("SupportsImplicitResolvingMSAA") for more details.
    color0_tex_desc.storage_mode = StorageMode::kDevicePrivate;
  }
 
  auto color0_msaa_tex = allocator.CreateTexture(color0_tex_desc);
  if (!color0_msaa_tex) {
    VALIDATION_LOG << "Could not create multisample color texture.";
    return {};
  }
  color0_msaa_tex->SetLabel(
      SPrintF("%s Color Texture (Multisample)", label.c_str()));
 
  // Create color resolve texture.
 
  TextureDescriptor color0_resolve_tex_desc;
  color0_resolve_tex_desc.storage_mode =
      color_attachment_config.resolve_storage_mode;
  color0_resolve_tex_desc.format = pixel_format;
  color0_resolve_tex_desc.size = size;
  color0_resolve_tex_desc.compression_type = CompressionType::kLossy;
  color0_resolve_tex_desc.usage =
      static_cast<uint64_t>(TextureUsage::kRenderTarget) |
      static_cast<uint64_t>(TextureUsage::kShaderRead);
 
  auto color0_resolve_tex = allocator.CreateTexture(color0_resolve_tex_desc);
  if (!color0_resolve_tex) {
    VALIDATION_LOG << "Could not create color texture.";
    return {};
  }
  color0_resolve_tex->SetLabel(SPrintF("%s Color Texture", label.c_str()));
 
  // Color attachment.
 
  ColorAttachment color0;
  color0.clear_color = color_attachment_config.clear_color;
  color0.load_action = color_attachment_config.load_action;
  color0.store_action = color_attachment_config.store_action;
  color0.texture = color0_msaa_tex;
  color0.resolve_texture = color0_resolve_tex;
 
  if (context.GetCapabilities()->SupportsImplicitResolvingMSAA()) {
    // If implicit MSAA is supported, then the resolve texture is not needed
    // because the multisample texture is automatically resolved. We instead
    // provide a view of the multisample texture as the resolve texture (because
    // the HAL does expect a resolve texture).
    //
    // In practice, this is used for GLES 2.0 EXT_multisampled_render_to_texture
    // https://registry.khronos.org/OpenGL/extensions/EXT/EXT_multisampled_render_to_texture.txt
    color0.resolve_texture = color0_msaa_tex;
  }
 
  target.SetColorAttachment(color0, 0u);
 
  // Create MSAA stencil texture.
 
  if (stencil_attachment_config.has_value()) {
    target.SetupStencilAttachment(context, allocator, size, true, label,
                                  stencil_attachment_config.value());
  } else {
    target.SetStencilAttachment(std::nullopt);
  }
 
  return target;
}

References impeller::RenderTarget::AttachmentConfigMSAA::clear_color, impeller::ColorAttachment::clear_color, impeller::TextureDescriptor::compression_type, impeller::RenderTargetAllocator::CreateTexture(), impeller::TextureDescriptor::format, impeller::Context::GetCapabilities(), impeller::TSize< T >::IsEmpty(), impeller::kCount4, impeller::kDevicePrivate, impeller::kLossy, impeller::kRenderTarget, impeller::kShaderRead, impeller::kTexture2DMultisample, impeller::RenderTarget::AttachmentConfigMSAA::load_action, impeller::Attachment::load_action, impeller::RenderTarget::AttachmentConfigMSAA::resolve_storage_mode, impeller::Attachment::resolve_texture, impeller::TextureDescriptor::sample_count, SetColorAttachment(), SetStencilAttachment(), SetupStencilAttachment(), impeller::TextureDescriptor::size, impeller::SPrintF(), impeller::TextureDescriptor::storage_mode, impeller::RenderTarget::AttachmentConfigMSAA::storage_mode, impeller::RenderTarget::AttachmentConfigMSAA::store_action, impeller::Attachment::store_action, impeller::Attachment::texture, impeller::TextureDescriptor::type, impeller::TextureDescriptor::usage, and VALIDATION_LOG.

Referenced by impeller::CreateRenderTarget(), impeller::ContentContext::MakeSubpass(), impeller::SceneContents::Render(), and impeller::testing::TEST_P().

GetColorAttachments()

const std::map< size_t, ColorAttachment > & impeller::RenderTarget::GetColorAttachments

(

)

const

Definition at line 209 of file render_target.cc.

          {
  return colors_;
}

Referenced by impeller::EntityPassTarget::Flip(), impeller::InlinePassContext::GetRenderPass(), impeller::GetVKClearValues(), and impeller::ToMTLRenderPassDescriptor().

GetColorAttachmentSize()

std::optional< ISize > impeller::RenderTarget::GetColorAttachmentSize

(

size_t

index

)

const

Definition at line 140 of file render_target.cc.

                                                                          {
  auto found = colors_.find(index);
 
  if (found == colors_.end()) {
    return std::nullopt;
  }
 
  return found->second.texture->GetSize();
}

Referenced by GetRenderTargetSize(), and impeller::Surface::Surface().

GetDepthAttachment()

const std::optional< DepthAttachment > & impeller::RenderTarget::GetDepthAttachment

(

)

const

Definition at line 214 of file render_target.cc.

                                                                           {
  return depth_;
}

Referenced by impeller::GetVKClearValues(), and impeller::ToMTLRenderPassDescriptor().

GetMaxColorAttacmentBindIndex()

size_t impeller::RenderTarget::GetMaxColorAttacmentBindIndex

(

)

const

Definition at line 172 of file render_target.cc.

                                                         {
  size_t max = 0;
  for (const auto& color : colors_) {
    max = std::max(color.first, max);
  }
  return max;
}

GetRenderTargetPixelFormat()

PixelFormat impeller::RenderTarget::GetRenderTargetPixelFormat

(

)

const

Definition at line 164 of file render_target.cc.

                                                           {
  if (auto texture = GetRenderTargetTexture(); texture != nullptr) {
    return texture->GetTextureDescriptor().format;
  }
 
  return PixelFormat::kUnknown;
}

References GetRenderTargetTexture(), and impeller::kUnknown.

GetRenderTargetSize()

ISize impeller::RenderTarget::GetRenderTargetSize

(

)

const

Definition at line 150 of file render_target.cc.

                                              {
  auto size = GetColorAttachmentSize(0u);
  return size.has_value() ? size.value() : ISize{};
}

References GetColorAttachmentSize().

Referenced by impeller::RenderPass::AddCommand(), and impeller::scene::Scene::Render().

GetRenderTargetTexture()

std::shared_ptr< Texture > impeller::RenderTarget::GetRenderTargetTexture

(

)

const

Definition at line 155 of file render_target.cc.

                                                                  {
  auto found = colors_.find(0u);
  if (found == colors_.end()) {
    return nullptr;
  }
  return found->second.resolve_texture ? found->second.resolve_texture
                                       : found->second.texture;
}

Referenced by GetRenderTargetPixelFormat(), impeller::InlinePassContext::GetTexture(), impeller::ContentContext::MakeSubpass(), and impeller::SceneContents::Render().

GetSampleCount()

SampleCount impeller::RenderTarget::GetSampleCount

(

)

const

Definition at line 126 of file render_target.cc.

                                               {
  if (auto found = colors_.find(0u); found != colors_.end()) {
    return found->second.texture->GetTextureDescriptor().sample_count;
  }
  return SampleCount::kCount1;
}

References impeller::kCount1.

Referenced by impeller::scene::Material::GetContextOptions().

GetStencilAttachment()

const std::optional< StencilAttachment > & impeller::RenderTarget::GetStencilAttachment

(

)

const

Definition at line 218 of file render_target.cc.

          {
  return stencil_;
}

Referenced by impeller::InlinePassContext::GetRenderPass(), impeller::GetVKClearValues(), and impeller::ToMTLRenderPassDescriptor().

GetTotalAttachmentCount()

size_t impeller::RenderTarget::GetTotalAttachmentCount

(

)

const

Definition at line 386 of file render_target.cc.

                                                   {
  size_t count = 0u;
  for (const auto& [_, color] : colors_) {
    if (color.texture) {
      count++;
    }
    if (color.resolve_texture) {
      count++;
    }
  }
  if (depth_.has_value()) {
    count++;
  }
  if (stencil_.has_value()) {
    count++;
  }
  return count;
}

HasColorAttachment()

bool impeller::RenderTarget::HasColorAttachment

(

size_t

index

)

const

Definition at line 133 of file render_target.cc.

                                                        {
  if (auto found = colors_.find(index); found != colors_.end()) {
    return true;
  }
  return false;
}

Referenced by IsValid().

IsValid()

bool impeller::RenderTarget::IsValid

(

)

const

Definition at line 34 of file render_target.cc.

                                 {
  // Validate that there is a color attachment at zero index.
  if (!HasColorAttachment(0u)) {
    VALIDATION_LOG
        << "Render target does not have color attachment at index 0.";
    return false;
  }
 
  // Validate that all attachments are of the same size.
  {
    std::optional<ISize> size;
    bool sizes_are_same = true;
    auto iterator = [&](const Attachment& attachment) -> bool {
      if (!size.has_value()) {
        size = attachment.texture->GetSize();
      }
      if (size != attachment.texture->GetSize()) {
        sizes_are_same = false;
        return false;
      }
      return true;
    };
    IterateAllAttachments(iterator);
    if (!sizes_are_same) {
      VALIDATION_LOG
          << "Sizes of all render target attachments are not the same.";
      return false;
    }
  }
 
  // Validate that all attachments are of the same type and sample counts.
  {
    std::optional<TextureType> texture_type;
    std::optional<SampleCount> sample_count;
    bool passes_type_validation = true;
    auto iterator = [&](const Attachment& attachment) -> bool {
      if (!texture_type.has_value() || !sample_count.has_value()) {
        texture_type = attachment.texture->GetTextureDescriptor().type;
        sample_count = attachment.texture->GetTextureDescriptor().sample_count;
      }
 
      if (texture_type != attachment.texture->GetTextureDescriptor().type) {
        passes_type_validation = false;
        VALIDATION_LOG << "Render target has incompatible texture types: "
                       << TextureTypeToString(texture_type.value()) << " != "
                       << TextureTypeToString(
                              attachment.texture->GetTextureDescriptor().type)
                       << " on target " << ToString();
        return false;
      }
 
      if (sample_count !=
          attachment.texture->GetTextureDescriptor().sample_count) {
        passes_type_validation = false;
        VALIDATION_LOG << "Render target (" << ToString()
                       << ") has incompatible sample counts.";
 
        return false;
      }
 
      return true;
    };
    IterateAllAttachments(iterator);
    if (!passes_type_validation) {
      return false;
    }
  }
 
  return true;
}

References HasColorAttachment(), IterateAllAttachments(), impeller::TextureTypeToString(), ToString(), and VALIDATION_LOG.

Referenced by impeller::EntityPassTarget::IsValid(), and impeller::SceneContents::Render().

IterateAllAttachments()

void impeller::RenderTarget::IterateAllAttachments

(

const std::function< bool(const Attachment &attachment)> &

iterator

)

const

Definition at line 105 of file render_target.cc.

                                                                           {
  for (const auto& color : colors_) {
    if (!iterator(color.second)) {
      return;
    }
  }
 
  if (depth_.has_value()) {
    if (!iterator(depth_.value())) {
      return;
    }
  }
 
  if (stencil_.has_value()) {
    if (!iterator(stencil_.value())) {
      return;
    }
  }
}

Referenced by IsValid().

SetColorAttachment()

RenderTarget & impeller::RenderTarget::SetColorAttachment	(	const ColorAttachment &	attachment,
		size_t	index
	)

Definition at line 180 of file render_target.cc.

                  {
  if (attachment.IsValid()) {
    colors_[index] = attachment;
  }
  return *this;
}

References impeller::Attachment::IsValid().

Referenced by CreateOffscreen(), CreateOffscreenMSAA(), impeller::EntityPassTarget::Flip(), impeller::InlinePassContext::GetRenderPass(), impeller::testing::TEST_P(), impeller::SurfaceGLES::WrapFBO(), and impeller::SurfaceVK::WrapSwapchainImage().

SetDepthAttachment()

RenderTarget & impeller::RenderTarget::SetDepthAttachment

(

std::optional< DepthAttachment >

attachment

)

Definition at line 189 of file render_target.cc.

                                             {
  if (!attachment.has_value()) {
    depth_ = std::nullopt;
  } else if (attachment->IsValid()) {
    depth_ = std::move(attachment);
  }
  return *this;
}

SetStencilAttachment()

RenderTarget & impeller::RenderTarget::SetStencilAttachment

(

std::optional< StencilAttachment >

attachment

)

Definition at line 199 of file render_target.cc.

                                               {
  if (!attachment.has_value()) {
    stencil_ = std::nullopt;
  } else if (attachment->IsValid()) {
    stencil_ = std::move(attachment);
  }
  return *this;
}

Referenced by CreateOffscreen(), CreateOffscreenMSAA(), impeller::InlinePassContext::GetRenderPass(), SetupStencilAttachment(), impeller::testing::TEST_P(), and impeller::SurfaceGLES::WrapFBO().

SetupStencilAttachment()

void impeller::RenderTarget::SetupStencilAttachment	(	const Context &	context,
		RenderTargetAllocator &	allocator,
		ISize	size,
		bool	msaa,
		const std::string &	label = "Offscreen",
		AttachmentConfig	stencil_attachment_config = kDefaultStencilAttachmentConfig
	)

Definition at line 355 of file render_target.cc.

                                                {
  TextureDescriptor stencil_tex0;
  stencil_tex0.storage_mode = stencil_attachment_config.storage_mode;
  if (msaa) {
    stencil_tex0.type = TextureType::kTexture2DMultisample;
    stencil_tex0.sample_count = SampleCount::kCount4;
  }
  stencil_tex0.format = context.GetCapabilities()->GetDefaultStencilFormat();
  stencil_tex0.size = size;
  stencil_tex0.usage =
      static_cast<TextureUsageMask>(TextureUsage::kRenderTarget);
 
  StencilAttachment stencil0;
  stencil0.load_action = stencil_attachment_config.load_action;
  stencil0.store_action = stencil_attachment_config.store_action;
  stencil0.clear_stencil = 0u;
  stencil0.texture = allocator.CreateTexture(stencil_tex0);
 
  if (!stencil0.texture) {
    return;  // Error messages are handled by `Allocator::CreateTexture`.
  }
  stencil0.texture->SetLabel(SPrintF("%s Stencil Texture", label.c_str()));
  SetStencilAttachment(std::move(stencil0));
}

References impeller::StencilAttachment::clear_stencil, impeller::RenderTargetAllocator::CreateTexture(), impeller::TextureDescriptor::format, impeller::Context::GetCapabilities(), impeller::kCount4, impeller::kRenderTarget, impeller::kTexture2DMultisample, impeller::RenderTarget::AttachmentConfig::load_action, impeller::Attachment::load_action, impeller::TextureDescriptor::sample_count, SetStencilAttachment(), impeller::TextureDescriptor::size, impeller::SPrintF(), impeller::TextureDescriptor::storage_mode, impeller::RenderTarget::AttachmentConfig::storage_mode, impeller::RenderTarget::AttachmentConfig::store_action, impeller::Attachment::store_action, impeller::Attachment::texture, impeller::TextureDescriptor::type, and impeller::TextureDescriptor::usage.

Referenced by CreateOffscreen(), and CreateOffscreenMSAA().

ToString()

std::string impeller::RenderTarget::ToString

(

)

const

Definition at line 405 of file render_target.cc.

                                       {
  std::stringstream stream;
 
  for (const auto& [index, color] : colors_) {
    stream << SPrintF("Color[%zu]=(%s)", index,
                      ColorAttachmentToString(color).c_str());
  }
  if (depth_) {
    stream << ",";
    stream << SPrintF("Depth=(%s)",
                      DepthAttachmentToString(depth_.value()).c_str());
  }
  if (stencil_) {
    stream << ",";
    stream << SPrintF("Stencil=(%s)",
                      StencilAttachmentToString(stencil_.value()).c_str());
  }
  return stream.str();
}

References impeller::ColorAttachmentToString(), impeller::DepthAttachmentToString(), impeller::SPrintF(), and impeller::StencilAttachmentToString().

Referenced by IsValid().

Member Data Documentation

kDefaultColorAttachmentConfig

constexpr AttachmentConfig impeller::RenderTarget::kDefaultColorAttachmentConfig

staticconstexpr

Initial value:

= {
      .storage_mode = StorageMode::kDevicePrivate,
      .load_action = LoadAction::kClear,
      .store_action = StoreAction::kStore,
      .clear_color = Color::BlackTransparent()}

Definition at line 66 of file render_target.h.

Referenced by impeller::ContentContext::MakeSubpass(), and impeller::testing::TEST_P().

kDefaultColorAttachmentConfigMSAA

constexpr AttachmentConfigMSAA impeller::RenderTarget::kDefaultColorAttachmentConfigMSAA

staticconstexpr

Initial value:

= {
      .storage_mode = StorageMode::kDeviceTransient,
      .resolve_storage_mode = StorageMode::kDevicePrivate,
      .load_action = LoadAction::kClear,
      .store_action = StoreAction::kMultisampleResolve,
      .clear_color = Color::BlackTransparent()}

Definition at line 72 of file render_target.h.

Referenced by impeller::ContentContext::MakeSubpass().

kDefaultStencilAttachmentConfig

constexpr AttachmentConfig impeller::RenderTarget::kDefaultStencilAttachmentConfig

staticconstexpr

Initial value:

= {
      .storage_mode = StorageMode::kDeviceTransient,
      .load_action = LoadAction::kClear,
      .store_action = StoreAction::kDontCare,
      .clear_color = Color::BlackTransparent()}

Definition at line 79 of file render_target.h.

---

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

• impeller/renderer/render_target.h
• impeller/renderer/render_target.cc