| Flutter Impeller |

Public Member Functions | Protected Member Functions | List of all members
impeller::BlitPass Class Referenceabstract

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 | ( |  | ) |
| virtual default

## ◆ BlitPass()

impeller::BlitPass::BlitPass | ( |  | ) |
| explicit protected

Definition at line 16 of file blit_pass.cc.

16 {}

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

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

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

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

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

165 {
166 return true;
167 }

## ◆ 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 169 of file blit_pass.cc.

170 {
171 if (!texture) {
172 VALIDATION_LOG << "Attempted to add an invalid mipmap generation command "
173 "with no texture.";
174 return false;
175 }
176
177 return OnGenerateMipmapCommand(std::move(texture), label);
178 }
impeller::BlitPass::OnGenerateMipmapCommand
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
| ) |  |
| protected pure 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
| ) |  |
| protected pure 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
| ) |  |
| protected pure virtual

Referenced by AddCopy().

## ◆ OnGenerateMipmapCommand()

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

Referenced by GenerateMipmap().

## ◆ OnSetLabel()

virtual void impeller::BlitPass::OnSetLabel | ( | std::string_view | label | ) |
| protected pure 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.

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

References OnSetLabel().

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

- impeller/renderer/blit_pass.h
- impeller/renderer/blit_pass.cc