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 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...
bool	AddCopy (std::shared_ptr< Texture > source, std::shared_ptr< Texture > destination, std::optional< IRect > source_region=std::nullopt, IPoint destination_origin={}, std::string 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 label="")
	Record a command to copy the contents of the buffer to the texture. More...
bool	AddCopy (BufferView source, std::shared_ptr< Texture > destination, std::optional< IRect > destination_region=std::nullopt, std::string label="", uint32_t slice=0, bool convert_to_read=true)
	Record a command to copy the contents of the buffer to the texture. More...
bool	GenerateMipmap (std::shared_ptr< Texture > texture, std::string label="")
	Record a command to generate all mip levels for a texture. More...
virtual bool	EncodeCommands (const std::shared_ptr< Allocator > &transients_allocator) const =0
	Encode the recorded commands to the underlying command buffer. More...

Protected Member Functions
	BlitPass ()
virtual void	OnSetLabel (std::string label)=0
virtual bool	OnCopyTextureToTextureCommand (std::shared_ptr< Texture > source, std::shared_ptr< Texture > destination, IRect source_region, IPoint destination_origin, std::string label)=0
virtual bool	OnCopyTextureToBufferCommand (std::shared_ptr< Texture > source, std::shared_ptr< DeviceBuffer > destination, IRect source_region, size_t destination_offset, std::string label)=0
virtual bool	OnCopyBufferToTextureCommand (BufferView source, std::shared_ptr< Texture > destination, IRect destination_region, std::string label, uint32_t slice, bool convert_to_read)=0
virtual bool	OnGenerateMipmapCommand (std::shared_ptr< Texture > texture, std::string 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 26 of file blit_pass.h.

Constructor & Destructor Documentation

~BlitPass()

impeller::BlitPass::~BlitPass ( )

virtualdefault

BlitPass()

impeller::BlitPass::BlitPass ( )

explicitprotected

Definition at line 15 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	label = "",
		uint32_t	slice = 0,
		bool	convert_to_read = true
	)

Record a command to copy the contents of the buffer to the 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]	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 123 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_pixel =
      BytesPerPixelForPixelFormat(destination->GetTextureDescriptor().format);
  auto bytes_per_region = destination_region_value.Area() * bytes_per_pixel;
 
  if (source.range.length != bytes_per_region) {
    VALIDATION_LOG
        << "Attempted to add a texture blit with out of bounds access.";
    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,
                                      std::move(label), slice, convert_to_read);
}

References impeller::TRect< T >::Area(), impeller::BytesPerPixelForPixelFormat(), impeller::TRect< T >::GetBottom(), impeller::TRect< T >::GetRight(), impeller::TRect< T >::GetX(), impeller::TRect< T >::GetY(), impeller::TSize< T >::height, impeller::Range::length, impeller::TRect< T >::MakeSize(), OnCopyBufferToTextureCommand(), impeller::BufferView::range, 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	label = ""
	)

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

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 83 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,
                                      std::move(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	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 26 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 << SPrintF(
        "The source sample count (%d) must match the destination sample count "
        "(%d) 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 << SPrintF(
        "The source pixel format (%s) must match the destination pixel format "
        "(%s) "
        "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.
  }
 
  // Clip the destination image.
  source_region = source_region->Intersection(
      IRect::MakeOriginSize(-destination_origin, destination->GetSize()));
  if (!source_region.has_value()) {
    return true;  // Nothing to blit.
  }
 
  return OnCopyTextureToTextureCommand(
      std::move(source), std::move(destination), source_region.value(),
      destination_origin, std::move(label));
}

References impeller::TRect< T >::MakeOriginSize(), impeller::TRect< T >::MakeSize(), OnCopyTextureToTextureCommand(), impeller::PixelFormatToString(), impeller::SPrintF(), 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 163 of file blit_pass.cc.

                                           {
  return true;
}

EncodeCommands()

virtual bool impeller::BlitPass::EncodeCommands ( const std::shared_ptr< Allocator > &  transients_allocator ) const

pure virtual

Encode the recorded commands to the underlying command buffer.

Parameters

transients_allocator

The transients allocator.

Returns

If the commands were encoded to the underlying command buffer.

GenerateMipmap()

bool impeller::BlitPass::GenerateMipmap	(	std::shared_ptr< Texture >	texture,
		std::string	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 168 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), std::move(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  label, 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  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  label  )

protectedpure virtual

Referenced by AddCopy().

OnGenerateMipmapCommand()

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

protectedpure virtual

Referenced by GenerateMipmap().

OnSetLabel()

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

protectedpure virtual

Referenced by SetLabel().

SetLabel()

void impeller::BlitPass::SetLabel

(

std::string

label

)

Definition at line 19 of file blit_pass.cc.

                                       {
  if (label.empty()) {
    return;
  }
  OnSetLabel(std::move(label));
}

References OnSetLabel().

---

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

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