impeller::BlitPass Class Reference

Blit passes encode blit into the underlying command buffer. More...

#include <blit_pass.h>

Inheritance diagram for impeller::BlitPass:

Public Member Functions
virtual	~BlitPass ()
virtual bool	IsValid () const =0
void	SetLabel (std::string_view label)
virtual bool	ConvertTextureToShaderRead (const std::shared_ptr< Texture > &texture)
	If the texture is not already in a shader read internal state, then convert it to that state. More...
virtual bool	ResizeTexture (const std::shared_ptr< Texture > &source, const std::shared_ptr< Texture > &destination)=0
	Resize the [source] texture into the [destination] texture. More...
bool	AddCopy (std::shared_ptr< Texture > source, std::shared_ptr< Texture > destination, std::optional< IRect > source_region=std::nullopt, IPoint destination_origin={}, std::string_view label="")
	Record a command to copy the contents of one texture to another texture. The blit area is limited by the intersection of the texture coverage with respect the source region and destination origin. More...
bool	AddCopy (std::shared_ptr< Texture > source, std::shared_ptr< DeviceBuffer > destination, std::optional< IRect > source_region=std::nullopt, size_t destination_offset=0, std::string_view label="")
	Record a command to copy the contents of a texture to a buffer. More...
bool	AddCopy (BufferView source, std::shared_ptr< Texture > destination, std::optional< IRect > destination_region=std::nullopt, std::string_view label="", uint32_t mip_level=0, uint32_t slice=0, bool convert_to_read=true)
	Record a command to copy the contents of a buffer to a texture. More...
bool	GenerateMipmap (std::shared_ptr< Texture > texture, std::string_view label="")
	Record a command to generate all mip levels for a texture. More...
virtual bool	EncodeCommands () const =0
	Encode the recorded commands to the underlying command buffer. More...

Protected Member Functions
	BlitPass ()
virtual void	OnSetLabel (std::string_view label)=0
virtual bool	OnCopyTextureToTextureCommand (std::shared_ptr< Texture > source, std::shared_ptr< Texture > destination, IRect source_region, IPoint destination_origin, std::string_view label)=0
virtual bool	OnCopyTextureToBufferCommand (std::shared_ptr< Texture > source, std::shared_ptr< DeviceBuffer > destination, IRect source_region, size_t destination_offset, std::string_view label)=0
virtual bool	OnCopyBufferToTextureCommand (BufferView source, std::shared_ptr< Texture > destination, IRect destination_region, std::string_view label, uint32_t mip_level, uint32_t slice, bool convert_to_read)=0
virtual bool	OnGenerateMipmapCommand (std::shared_ptr< Texture > texture, std::string_view label)=0

Detailed Description

Blit passes encode blit into the underlying command buffer.

        Blit passes can be obtained from the command buffer in which
        the pass is meant to encode commands into.

See also

CommandBuffer

Definition at line 27 of file blit_pass.h.

Constructor & Destructor Documentation

~BlitPass()

impeller::BlitPass::~BlitPass ( )

virtualdefault

BlitPass()

impeller::BlitPass::BlitPass ( )

explicitprotected

Definition at line 16 of file blit_pass.cc.

{}

Member Function Documentation

AddCopy() [1/3]

bool impeller::BlitPass::AddCopy	(	BufferView	source,
		std::shared_ptr< Texture >	destination,
		std::optional< IRect >	destination_region = std::nullopt,
		std::string_view	label = "",
		uint32_t	mip_level = 0,
		uint32_t	slice = 0,
		bool	convert_to_read = true
	)

Record a command to copy the contents of a buffer to a texture.

Parameters

[in]	source	The buffer view to read for copying.
[in]	destination	The texture to overwrite using the source contents.
[in]	destination_region	The offset to start writing to in the destination texture. If not provided, this defaults to the entire texture.
[in]	label	The optional debug label to give the command.
[in]	mip_level	The mip level to write to.
[in]	slice	For cubemap textures, the slice to write data to.
[in]	convert_to_read	Whether to convert the texture to a shader read state. Defaults to true.

Returns

If the command was valid for subsequent commitment.

If a region smaller than the texture size is provided, the contents are treated as containing tightly packed pixel data of that region. Only the portion of the texture in this region is replaced and existing data is preserved.

For example, to replace the top left 10 x 10 region of a larger 100 x 100 texture, the region is {0, 0, 10, 10} and the expected buffer size in bytes is 100 x bpp.

Definition at line 117 of file blit_pass.cc.

                                             {
  if (!destination) {
    VALIDATION_LOG << "Attempted to add a texture blit with no destination.";
    return false;
  }
  ISize destination_size = destination->GetSize();
  IRect destination_region_value =
      destination_region.value_or(IRect::MakeSize(destination_size));
  if (destination_region_value.GetX() < 0 ||
      destination_region_value.GetY() < 0 ||
      destination_region_value.GetRight() > destination_size.width ||
      destination_region_value.GetBottom() > destination_size.height) {
    VALIDATION_LOG << "Blit region cannot be larger than destination texture.";
    return false;
  }
 
  auto bytes_per_region =
      BytesForTextureRegion(destination->GetTextureDescriptor().format,
                            destination_region_value.GetWidth(),
                            destination_region_value.GetHeight());
 
  if (source.GetRange().length != bytes_per_region) {
    VALIDATION_LOG
        << "Attempted to add a texture blit with out of bounds access.";
    return false;
  }
  if (mip_level >= destination->GetMipCount()) {
    VALIDATION_LOG << "Invalid value for mip_level: " << mip_level << ". "
                   << "The destination texture has "
                   << destination->GetMipCount() << " mip levels.";
    return false;
  }
  if (slice > 5) {
    VALIDATION_LOG << "Invalid value for slice: " << slice;
    return false;
  }
 
  return OnCopyBufferToTextureCommand(std::move(source), std::move(destination),
                                      destination_region_value, label,
                                      mip_level, slice, convert_to_read);
}

References impeller::BytesForTextureRegion(), impeller::TRect< T >::GetBottom(), impeller::TRect< T >::GetHeight(), impeller::BufferView::GetRange(), impeller::TRect< T >::GetRight(), impeller::TRect< T >::GetWidth(), impeller::TRect< T >::GetX(), impeller::TRect< T >::GetY(), impeller::TSize< T >::height, impeller::Range::length, impeller::TRect< T >::MakeSize(), OnCopyBufferToTextureCommand(), VALIDATION_LOG, and impeller::TSize< T >::width.

AddCopy() [2/3]

bool impeller::BlitPass::AddCopy	(	std::shared_ptr< Texture >	source,
		std::shared_ptr< DeviceBuffer >	destination,
		std::optional< IRect >	source_region = std::nullopt,
		size_t	destination_offset = 0,
		std::string_view	label = ""
	)

Record a command to copy the contents of a texture to a buffer.

Parameters

[in]	source	The texture to read for copying.
[in]	destination	The buffer to overwrite using the source contents.
[in]	source_region	The optional region of the source texture to use for copying. If not specified, the full size of the source texture is used.
[in]	destination_origin	The origin to start writing to in the destination texture.
[in]	label	The optional debug label to give the command.

Returns

If the command was valid for subsequent commitment.

Definition at line 77 of file blit_pass.cc.

                                             {
  if (!source) {
    VALIDATION_LOG << "Attempted to add a texture blit with no source.";
    return false;
  }
  if (!destination) {
    VALIDATION_LOG << "Attempted to add a texture blit with no destination.";
    return false;
  }
 
  if (!source_region.has_value()) {
    source_region = IRect::MakeSize(source->GetSize());
  }
 
  auto bytes_per_pixel =
      BytesPerPixelForPixelFormat(source->GetTextureDescriptor().format);
  auto bytes_per_image = source_region->Area() * bytes_per_pixel;
  if (destination_offset + bytes_per_image >
      destination->GetDeviceBufferDescriptor().size) {
    VALIDATION_LOG
        << "Attempted to add a texture blit with out of bounds access.";
    return false;
  }
 
  // Clip the source image.
  source_region =
      source_region->Intersection(IRect::MakeSize(source->GetSize()));
  if (!source_region.has_value()) {
    return true;  // Nothing to blit.
  }
 
  return OnCopyTextureToBufferCommand(std::move(source), std::move(destination),
                                      source_region.value(), destination_offset,
                                      label);
}

References impeller::BytesPerPixelForPixelFormat(), impeller::TRect< T >::MakeSize(), OnCopyTextureToBufferCommand(), and VALIDATION_LOG.

AddCopy() [3/3]

bool impeller::BlitPass::AddCopy	(	std::shared_ptr< Texture >	source,
		std::shared_ptr< Texture >	destination,
		std::optional< IRect >	source_region = std::nullopt,
		IPoint	destination_origin = {},
		std::string_view	label = ""
	)

Record a command to copy the contents of one texture to another texture. The blit area is limited by the intersection of the texture coverage with respect the source region and destination origin.

Parameters

[in]	source	The texture to read for copying.
[in]	destination	The texture to overwrite using the source contents.
[in]	source_region	The optional region of the source texture to use for copying. If not specified, the full size of the source texture is used.
[in]	destination_origin	The origin to start writing to in the destination texture.
[in]	label	The optional debug label to give the command.

Returns

If the command was valid for subsequent commitment.

Definition at line 27 of file blit_pass.cc.

                                             {
  if (!source) {
    VALIDATION_LOG << "Attempted to add a texture blit with no source.";
    return false;
  }
  if (!destination) {
    VALIDATION_LOG << "Attempted to add a texture blit with no destination.";
    return false;
  }
 
  if (source->GetTextureDescriptor().sample_count !=
      destination->GetTextureDescriptor().sample_count) {
    VALIDATION_LOG << std::format(
        "The source sample count ({}) must match the destination sample count "
        "({}) for blits.",
        static_cast<int>(source->GetTextureDescriptor().sample_count),
        static_cast<int>(destination->GetTextureDescriptor().sample_count));
    return false;
  }
  if (source->GetTextureDescriptor().format !=
      destination->GetTextureDescriptor().format) {
    VALIDATION_LOG << std::format(
        "The source pixel format ({}) must match the destination pixel format "
        "({}) "
        "for blits.",
        PixelFormatToString(source->GetTextureDescriptor().format),
        PixelFormatToString(destination->GetTextureDescriptor().format));
    return false;
  }
 
  if (!source_region.has_value()) {
    source_region = IRect::MakeSize(source->GetSize());
  }
 
  // Clip the source image.
  source_region =
      source_region->Intersection(IRect::MakeSize(source->GetSize()));
  if (!source_region.has_value()) {
    return true;  // Nothing to blit.
  }
 
  return OnCopyTextureToTextureCommand(
      std::move(source), std::move(destination), source_region.value(),
      destination_origin, label);
}

References impeller::TRect< T >::MakeSize(), OnCopyTextureToTextureCommand(), impeller::PixelFormatToString(), and VALIDATION_LOG.

ConvertTextureToShaderRead()

bool impeller::BlitPass::ConvertTextureToShaderRead ( const std::shared_ptr< Texture > &  texture )

virtual

If the texture is not already in a shader read internal state, then convert it to that state.

This API is only used by Vulkan.

Definition at line 165 of file blit_pass.cc.

                                           {
  return true;
}

EncodeCommands()

virtual bool impeller::BlitPass::EncodeCommands ( ) const

pure virtual

Encode the recorded commands to the underlying command buffer.

Returns

If the commands were encoded to the underlying command buffer.

GenerateMipmap()

bool impeller::BlitPass::GenerateMipmap	(	std::shared_ptr< Texture >	texture,
		std::string_view	label = ""
	)

Record a command to generate all mip levels for a texture.

Parameters

[in]	texture	The texture to generate mipmaps for.
[in]	label	The optional debug label to give the command.

Returns

If the command was valid for subsequent commitment.

Definition at line 170 of file blit_pass.cc.

                                                    {
  if (!texture) {
    VALIDATION_LOG << "Attempted to add an invalid mipmap generation command "
                      "with no texture.";
    return false;
  }
 
  return OnGenerateMipmapCommand(std::move(texture), label);
}

References OnGenerateMipmapCommand(), and VALIDATION_LOG.

IsValid()

virtual bool impeller::BlitPass::IsValid ( ) const

pure virtual

OnCopyBufferToTextureCommand()

virtual bool impeller::BlitPass::OnCopyBufferToTextureCommand ( BufferView  source, std::shared_ptr< Texture >  destination, IRect  destination_region, std::string_view  label, uint32_t  mip_level, uint32_t  slice, bool  convert_to_read  )

protectedpure virtual

Referenced by AddCopy().

OnCopyTextureToBufferCommand()

virtual bool impeller::BlitPass::OnCopyTextureToBufferCommand ( std::shared_ptr< Texture >  source, std::shared_ptr< DeviceBuffer >  destination, IRect  source_region, size_t  destination_offset, std::string_view  label  )

protectedpure virtual

Referenced by AddCopy().

OnCopyTextureToTextureCommand()

virtual bool impeller::BlitPass::OnCopyTextureToTextureCommand ( std::shared_ptr< Texture >  source, std::shared_ptr< Texture >  destination, IRect  source_region, IPoint  destination_origin, std::string_view  label  )

protectedpure virtual

Referenced by AddCopy().

OnGenerateMipmapCommand()

virtual bool impeller::BlitPass::OnGenerateMipmapCommand ( std::shared_ptr< Texture >  texture, std::string_view  label  )

protectedpure virtual

Referenced by GenerateMipmap().

OnSetLabel()

virtual void impeller::BlitPass::OnSetLabel ( std::string_view  label )

protectedpure virtual

Referenced by SetLabel().

ResizeTexture()

virtual bool impeller::BlitPass::ResizeTexture ( const std::shared_ptr< Texture > &  source, const std::shared_ptr< Texture > &  destination  )

pure virtual

Resize the [source] texture into the [destination] texture.

        On Metal platforms, [destination] is required to be non-lossy
        and have the Shader read capability. 

SetLabel()

void impeller::BlitPass::SetLabel

(

std::string_view

label

)

Definition at line 20 of file blit_pass.cc.

                                            {
  if (label.empty()) {
    return;
  }
  OnSetLabel(label);
}

References OnSetLabel().

---

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

• impeller/renderer/blit_pass.h
• impeller/renderer/blit_pass.cc