| Flutter Impeller |

Public Member Functions | Protected Member Functions | Protected Attributes | 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 label)
HostBuffer & | GetTransientsBuffer ()
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. No work is encoded into the command buffer at this time. 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. No work is encoded into the command buffer at this time. More...
bool | AddCopy (BufferView source, std::shared_ptr< Texture > destination, IPoint destination_origin={}, std::string label="")
| Record a command to copy the contents of the buffer to the texture. No work is encoded into the command buffer at this time. More...
bool | GenerateMipmap (std::shared_ptr< Texture > texture, std::string label="")
| Record a command to generate all mip levels for a texture. No work is encoded into the command buffer at this time. 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, IPoint destination_origin, std::string label)=0
virtual bool | OnGenerateMipmapCommand (std::shared_ptr< Texture > texture, std::string label)=0

## Protected Attributes
std::shared_ptr< HostBuffer > | transients_buffer_

## 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 28 of file blit_pass.h.

## Constructor & Destructor Documentation

## ◆ ~BlitPass()

impeller::BlitPass::~BlitPass | ( |  | ) |
| virtual default

## ◆ BlitPass()

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

Definition at line 17 of file blit_pass.cc.

17 : transients_buffer_(HostBuffer::Create()) {}

## Member Function Documentation

## ◆ AddCopy() [1/3]

bool impeller::BlitPass::AddCopy | ( | BufferView | source,
|  | std::shared_ptr< Texture > | destination,
|  | IPoint | destination_origin = `{}`,
|  | std::string | label = `""`
| ) |  |

Record a command to copy the contents of the buffer to the texture. No work is encoded into the command buffer at this time.

Parameters

  [in] | source | The buffer view to read for copying.
  [in] | destination | The texture to overwrite using the source contents.
  [in] | destination_offset | The offset to start writing to in the destination buffer.
  [in] | label | The optional debug label to give the command.

Returns
  If the command was valid for subsequent commitment.

Definition at line 130 of file blit_pass.cc.

133 {
134 if (!destination) {
135 VALIDATION_LOG << "Attempted to add a texture blit with no destination.";
136 return false;
137 }
138
139 auto bytes_per_pixel =
140 BytesPerPixelForPixelFormat(destination->GetTextureDescriptor().format);
141 auto bytes_per_image =
142 destination->GetTextureDescriptor().size.Area() * bytes_per_pixel;
143
144 if (source.range.length != bytes_per_image) {
145 VALIDATION_LOG
146 << "Attempted to add a texture blit with out of bounds access.";
147 return false;
148 }
149
150 return OnCopyBufferToTextureCommand(std::move(source), std::move(destination),
151 destination_origin, std::move(label));
152 }

References impeller::BytesPerPixelForPixelFormat(), impeller::Range::length, OnCopyBufferToTextureCommand(), impeller::BufferView::range, and VALIDATION_LOG.

## ◆ 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. No work is encoded into the command buffer at this time.

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

94 {
95 if (!source) {
96 VALIDATION_LOG << "Attempted to add a texture blit with no source.";
97 return false;
98 }
99 if (!destination) {
100 VALIDATION_LOG << "Attempted to add a texture blit with no destination.";
101 return false;
102 }
103
104 if (!source_region.has_value()) {
105 source_region = IRect::MakeSize(source->GetSize());
106 }
107
108 auto bytes_per_pixel =
109 BytesPerPixelForPixelFormat(source->GetTextureDescriptor().format);
110 auto bytes_per_image = source_region->Area() * bytes_per_pixel;
111 if (destination_offset + bytes_per_image >
112 destination->GetDeviceBufferDescriptor().size) {
113 VALIDATION_LOG
114 << "Attempted to add a texture blit with out of bounds access.";
115 return false;
116 }
117
118 // Clip the source image.
119 source_region =
120 source_region->Intersection(IRect::MakeSize(source->GetSize()));
121 if (!source_region.has_value()) {
122 return true; // Nothing to blit.
123 }
124
125 return OnCopyTextureToBufferCommand(std::move(source), std::move(destination),
126 source_region.value(), destination_offset,
127 std::move(label));
128 }

References impeller::BytesPerPixelForPixelFormat(), impeller::TRect< int64_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. No work is encoded into the command buffer at this time.

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

37 {
38 if (!source) {
39 VALIDATION_LOG << "Attempted to add a texture blit with no source.";
40 return false;
41 }
42 if (!destination) {
43 VALIDATION_LOG << "Attempted to add a texture blit with no destination.";
44 return false;
45 }
46
47 if (source->GetTextureDescriptor().sample_count !=
48 destination->GetTextureDescriptor().sample_count) {
49 VALIDATION_LOG << SPrintF(
50 "The source sample count (%d) must match the destination sample count "
51 "(%d) for blits.",
52 static_cast<int>(source->GetTextureDescriptor().sample_count),
53 static_cast<int>(destination->GetTextureDescriptor().sample_count));
54 return false;
55 }
56 if (source->GetTextureDescriptor().format !=
57 destination->GetTextureDescriptor().format) {
58 VALIDATION_LOG << SPrintF(
59 "The source pixel format (%s) must match the destination pixel format "
60 "(%s) "
61 "for blits.",
62 PixelFormatToString(source->GetTextureDescriptor().format),
63 PixelFormatToString(destination->GetTextureDescriptor().format));
64 return false;
65 }
66
67 if (!source_region.has_value()) {
68 source_region = IRect::MakeSize(source->GetSize());
69 }
70
71 // Clip the source image.
72 source_region =
73 source_region->Intersection(IRect::MakeSize(source->GetSize()));
74 if (!source_region.has_value()) {
75 return true; // Nothing to blit.
76 }
77
78 // Clip the destination image.
79 source_region = source_region->Intersection(
80 IRect::MakeOriginSize(-destination_origin, destination->GetSize()));
81 if (!source_region.has_value()) {
82 return true; // Nothing to blit.
83 }
84
85 return OnCopyTextureToTextureCommand(
86 std::move(source), std::move(destination), source_region.value(),
87 destination_origin, std::move(label));
88 }

References impeller::TRect< int64_t >::MakeOriginSize(), impeller::TRect< int64_t >::MakeSize(), OnCopyTextureToTextureCommand(), impeller::PixelFormatToString(), impeller::SPrintF(), and VALIDATION_LOG.

## ◆ 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. No work is encoded into the command buffer at this time.

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

155 {
156 if (!texture) {
157 VALIDATION_LOG << "Attempted to add an invalid mipmap generation command "
158 "with no texture.";
159 return false;
160 }
161
162 return OnGenerateMipmapCommand(std::move(texture), std::move(label));
163 }

References OnGenerateMipmapCommand(), and VALIDATION_LOG.

## ◆ GetTransientsBuffer()

HostBuffer & impeller::BlitPass::GetTransientsBuffer | ( |  | ) |

Definition at line 21 of file blit_pass.cc.

21 {
22 return *transients_buffer_;
23 }

References transients_buffer_.

## ◆ IsValid()

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

## ◆ OnCopyBufferToTextureCommand()

virtual bool impeller::BlitPass::OnCopyBufferToTextureCommand | ( | BufferView | source,
|  | std::shared_ptr< Texture > | destination,
|  | IPoint | destination_origin,
|  | std::string | label
| ) |  |
| 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 | 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 | label
| ) |  |
| protected pure virtual

Referenced by AddCopy().

## ◆ OnGenerateMipmapCommand()

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

Referenced by GenerateMipmap().

## ◆ OnSetLabel()

virtual void impeller::BlitPass::OnSetLabel | ( | std::string | label | ) |
| protected pure virtual

Referenced by SetLabel().

## ◆ SetLabel()

void impeller::BlitPass::SetLabel | ( | std::string | label | ) |

Definition at line 25 of file blit_pass.cc.

25 {
26 if (label.empty()) {
27 return;
28 }
29 transients_buffer_->SetLabel(SPrintF("%s Transients", label.c_str()));
30 OnSetLabel(std::move(label));
31 }

References OnSetLabel(), impeller::SPrintF(), and transients_buffer_.

## Member Data Documentation

## ◆ transients_buffer_

std::shared_ptr<HostBuffer> impeller::BlitPass::transients_buffer_
| protected

Definition at line 131 of file blit_pass.h.

Referenced by GetTransientsBuffer(), and SetLabel().

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

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

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 label)=0
impeller::PixelFormatToString
constexpr const char * PixelFormatToString(PixelFormat format)
Definition: formats.h:135
impeller::BlitPass::OnCopyTextureToTextureCommand
virtual bool OnCopyTextureToTextureCommand(std::shared_ptr< Texture > source, std::shared_ptr< Texture > destination, IRect source_region, IPoint destination_origin, std::string label)=0
impeller::BlitPass::OnCopyBufferToTextureCommand
virtual bool OnCopyBufferToTextureCommand(BufferView source, std::shared_ptr< Texture > destination, IPoint destination_origin, std::string label)=0
impeller::HostBuffer::Create
static std::shared_ptr< HostBuffer > Create()
Definition: host_buffer.cc:18
impeller::BytesPerPixelForPixelFormat
constexpr size_t BytesPerPixelForPixelFormat(PixelFormat format)
Definition: formats.h:442
impeller::SPrintF
std::string SPrintF(const char *format,...)
Definition: strings.cc:12
impeller::TRect< int64_t >::MakeOriginSize
constexpr static TRect MakeOriginSize(const TPoint< Type > &origin, const TSize< Type > &size)
Definition: rect.h:38
impeller::BlitPass::OnGenerateMipmapCommand
virtual bool OnGenerateMipmapCommand(std::shared_ptr< Texture > texture, std::string label)=0
impeller::BlitPass::OnSetLabel
virtual void OnSetLabel(std::string label)=0
VALIDATION_LOG
#define VALIDATION_LOG
Definition: validation.h:67
impeller::BlitPass::transients_buffer_
std::shared_ptr< HostBuffer > transients_buffer_
Definition: blit_pass.h:131
impeller::TRect< int64_t >::MakeSize
constexpr static TRect MakeSize(const TSize< U > &size)
Definition: rect.h:44