Flutter Impeller
impeller::BlitPass Class Referenceabstract

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

#include <blit_pass.h>

Inheritance diagram for impeller::BlitPass:
impeller::BlitPassGLES impeller::BlitPassMTL impeller::BlitPassVK

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 15 of file blit_pass.cc.

15 {}

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]sourceThe buffer view to read for copying.
[in]destinationThe texture to overwrite using the source contents.
[in]destination_regionThe offset to start writing to in the destination texture. If not provided, this defaults to the entire texture.
[in]labelThe optional debug label to give the command.
[in]mip_levelThe mip level to write to.
[in]sliceFor cubemap textures, the slice to write data to.
[in]convert_to_readWhether 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 116 of file blit_pass.cc.

122  {
123  if (!destination) {
124  VALIDATION_LOG << "Attempted to add a texture blit with no destination.";
125  return false;
126  }
127  ISize destination_size = destination->GetSize();
128  IRect destination_region_value =
129  destination_region.value_or(IRect::MakeSize(destination_size));
130  if (destination_region_value.GetX() < 0 ||
131  destination_region_value.GetY() < 0 ||
132  destination_region_value.GetRight() > destination_size.width ||
133  destination_region_value.GetBottom() > destination_size.height) {
134  VALIDATION_LOG << "Blit region cannot be larger than destination texture.";
135  return false;
136  }
137 
138  auto bytes_per_pixel =
139  BytesPerPixelForPixelFormat(destination->GetTextureDescriptor().format);
140  auto bytes_per_region = destination_region_value.Area() * bytes_per_pixel;
141 
142  if (source.GetRange().length != bytes_per_region) {
144  << "Attempted to add a texture blit with out of bounds access.";
145  return false;
146  }
147  if (mip_level >= destination->GetMipCount()) {
148  VALIDATION_LOG << "Invalid value for mip_level: " << mip_level << ". "
149  << "The destination texture has "
150  << destination->GetMipCount() << " mip levels.";
151  return false;
152  }
153  if (slice > 5) {
154  VALIDATION_LOG << "Invalid value for slice: " << slice;
155  return false;
156  }
157 
158  return OnCopyBufferToTextureCommand(std::move(source), std::move(destination),
159  destination_region_value, label,
160  mip_level, slice, convert_to_read);
161 }
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
constexpr size_t BytesPerPixelForPixelFormat(PixelFormat format)
Definition: formats.h:466
IRect64 IRect
Definition: rect.h:795
ISize64 ISize
Definition: size.h:162
constexpr static TRect MakeSize(const TSize< U > &size)
Definition: rect.h:150
#define VALIDATION_LOG
Definition: validation.h:91

References impeller::TRect< T >::Area(), impeller::BytesPerPixelForPixelFormat(), impeller::TRect< T >::GetBottom(), impeller::BufferView::GetRange(), impeller::TRect< T >::GetRight(), 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]sourceThe texture to read for copying.
[in]destinationThe buffer to overwrite using the source contents.
[in]source_regionThe optional region of the source texture to use for copying. If not specified, the full size of the source texture is used.
[in]destination_originThe origin to start writing to in the destination texture.
[in]labelThe optional debug label to give the command.
Returns
If the command was valid for subsequent commitment.

Definition at line 76 of file blit_pass.cc.

80  {
81  if (!source) {
82  VALIDATION_LOG << "Attempted to add a texture blit with no source.";
83  return false;
84  }
85  if (!destination) {
86  VALIDATION_LOG << "Attempted to add a texture blit with no destination.";
87  return false;
88  }
89 
90  if (!source_region.has_value()) {
91  source_region = IRect::MakeSize(source->GetSize());
92  }
93 
94  auto bytes_per_pixel =
95  BytesPerPixelForPixelFormat(source->GetTextureDescriptor().format);
96  auto bytes_per_image = source_region->Area() * bytes_per_pixel;
97  if (destination_offset + bytes_per_image >
98  destination->GetDeviceBufferDescriptor().size) {
100  << "Attempted to add a texture blit with out of bounds access.";
101  return false;
102  }
103 
104  // Clip the source image.
105  source_region =
106  source_region->Intersection(IRect::MakeSize(source->GetSize()));
107  if (!source_region.has_value()) {
108  return true; // Nothing to blit.
109  }
110 
111  return OnCopyTextureToBufferCommand(std::move(source), std::move(destination),
112  source_region.value(), destination_offset,
113  label);
114 }
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

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]sourceThe texture to read for copying.
[in]destinationThe texture to overwrite using the source contents.
[in]source_regionThe optional region of the source texture to use for copying. If not specified, the full size of the source texture is used.
[in]destination_originThe origin to start writing to in the destination texture.
[in]labelThe 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.

30  {
31  if (!source) {
32  VALIDATION_LOG << "Attempted to add a texture blit with no source.";
33  return false;
34  }
35  if (!destination) {
36  VALIDATION_LOG << "Attempted to add a texture blit with no destination.";
37  return false;
38  }
39 
40  if (source->GetTextureDescriptor().sample_count !=
41  destination->GetTextureDescriptor().sample_count) {
43  "The source sample count (%d) must match the destination sample count "
44  "(%d) for blits.",
45  static_cast<int>(source->GetTextureDescriptor().sample_count),
46  static_cast<int>(destination->GetTextureDescriptor().sample_count));
47  return false;
48  }
49  if (source->GetTextureDescriptor().format !=
50  destination->GetTextureDescriptor().format) {
52  "The source pixel format (%s) must match the destination pixel format "
53  "(%s) "
54  "for blits.",
55  PixelFormatToString(source->GetTextureDescriptor().format),
56  PixelFormatToString(destination->GetTextureDescriptor().format));
57  return false;
58  }
59 
60  if (!source_region.has_value()) {
61  source_region = IRect::MakeSize(source->GetSize());
62  }
63 
64  // Clip the source image.
65  source_region =
66  source_region->Intersection(IRect::MakeSize(source->GetSize()));
67  if (!source_region.has_value()) {
68  return true; // Nothing to blit.
69  }
70 
72  std::move(source), std::move(destination), source_region.value(),
73  destination_origin, label);
74 }
virtual bool OnCopyTextureToTextureCommand(std::shared_ptr< Texture > source, std::shared_ptr< Texture > destination, IRect source_region, IPoint destination_origin, std::string_view label)=0
std::string SPrintF(const char *format,...)
Definition: strings.cc:12
constexpr const char * PixelFormatToString(PixelFormat format)
Definition: formats.h:140

References 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.

164  {
165  return true;
166 }

◆ 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]textureThe texture to generate mipmaps for.
[in]labelThe 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.

169  {
170  if (!texture) {
171  VALIDATION_LOG << "Attempted to add an invalid mipmap generation command "
172  "with no texture.";
173  return false;
174  }
175 
176  return OnGenerateMipmapCommand(std::move(texture), label);
177 }
virtual bool OnGenerateMipmapCommand(std::shared_ptr< Texture > texture, std::string_view label)=0

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 19 of file blit_pass.cc.

19  {
20  if (label.empty()) {
21  return;
22  }
23  OnSetLabel(label);
24 }
virtual void OnSetLabel(std::string_view label)=0

References OnSetLabel().


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