Flutter Impeller
blit_pass.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef FLUTTER_IMPELLER_RENDERER_BLIT_PASS_H_
6 #define FLUTTER_IMPELLER_RENDERER_BLIT_PASS_H_
7 
8 #include <cstdint>
9 #include <string>
10 
12 #include "impeller/core/texture.h"
13 
14 namespace impeller {
15 
16 class HostBuffer;
17 class Allocator;
18 
19 //------------------------------------------------------------------------------
20 /// @brief Blit passes encode blit into the underlying command buffer.
21 ///
22 /// Blit passes can be obtained from the command buffer in which
23 /// the pass is meant to encode commands into.
24 ///
25 /// @see `CommandBuffer`
26 ///
27 class BlitPass {
28  public:
29  virtual ~BlitPass();
30 
31  virtual bool IsValid() const = 0;
32 
33  void SetLabel(std::string_view label);
34 
35  //----------------------------------------------------------------------------
36  /// @brief If the texture is not already in a shader read internal
37  /// state, then convert it to that state.
38  ///
39  /// This API is only used by Vulkan.
40  virtual bool ConvertTextureToShaderRead(
41  const std::shared_ptr<Texture>& texture);
42 
43  //----------------------------------------------------------------------------
44  /// @brief Resize the [source] texture into the [destination] texture.
45  ///
46  /// On Metal platforms, [destination] is required to be non-lossy
47  /// and have the Shader read capability.
48  virtual bool ResizeTexture(const std::shared_ptr<Texture>& source,
49  const std::shared_ptr<Texture>& destination) = 0;
50 
51  //----------------------------------------------------------------------------
52  /// @brief Record a command to copy the contents of one texture to
53  /// another texture. The blit area is limited by the intersection
54  /// of the texture coverage with respect the source region and
55  /// destination origin.
56  ///
57  /// @param[in] source The texture to read for copying.
58  /// @param[in] destination The texture to overwrite using the source
59  /// contents.
60  /// @param[in] source_region The optional region of the source texture
61  /// to use for copying. If not specified, the
62  /// full size of the source texture is used.
63  /// @param[in] destination_origin The origin to start writing to in the
64  /// destination texture.
65  /// @param[in] label The optional debug label to give the
66  /// command.
67  ///
68  /// @return If the command was valid for subsequent commitment.
69  ///
70  bool AddCopy(std::shared_ptr<Texture> source,
71  std::shared_ptr<Texture> destination,
72  std::optional<IRect> source_region = std::nullopt,
73  IPoint destination_origin = {},
74  std::string_view label = "");
75 
76  //----------------------------------------------------------------------------
77  /// @brief Record a command to copy the contents of a texture to a
78  /// buffer.
79  ///
80  /// @param[in] source The texture to read for copying.
81  /// @param[in] destination The buffer to overwrite using the source
82  /// contents.
83  /// @param[in] source_region The optional region of the source texture
84  /// to use for copying. If not specified, the
85  /// full size of the source texture is used.
86  /// @param[in] destination_origin The origin to start writing to in the
87  /// destination texture.
88  /// @param[in] label The optional debug label to give the
89  /// command.
90  ///
91  /// @return If the command was valid for subsequent commitment.
92  ///
93  bool AddCopy(std::shared_ptr<Texture> source,
94  std::shared_ptr<DeviceBuffer> destination,
95  std::optional<IRect> source_region = std::nullopt,
96  size_t destination_offset = 0,
97  std::string_view label = "");
98 
99  //----------------------------------------------------------------------------
100  /// @brief Record a command to copy the contents of a buffer to a
101  /// texture.
102  ///
103  /// @param[in] source The buffer view to read for copying.
104  /// @param[in] destination The texture to overwrite using the source
105  /// contents.
106  /// @param[in] destination_region The offset to start writing to in the
107  /// destination texture. If not provided, this
108  /// defaults to the entire texture.
109  /// @param[in] label The optional debug label to give the
110  /// command.
111  /// @param[in] mip_level The mip level to write to.
112  /// @param[in] slice For cubemap textures, the slice to write
113  /// data to.
114  /// @param[in] convert_to_read Whether to convert the texture to a shader
115  /// read state. Defaults to true.
116  ///
117  /// @return If the command was valid for subsequent commitment.
118  ///
119  /// If a region smaller than the texture size is provided, the
120  /// contents are treated as containing tightly packed pixel data of
121  /// that region. Only the portion of the texture in this region is
122  /// replaced and existing data is preserved.
123  ///
124  /// For example, to replace the top left 10 x 10 region of a larger
125  /// 100 x 100 texture, the region is {0, 0, 10, 10} and the expected
126  /// buffer size in bytes is 100 x bpp.
127  bool AddCopy(BufferView source,
128  std::shared_ptr<Texture> destination,
129  std::optional<IRect> destination_region = std::nullopt,
130  std::string_view label = "",
131  uint32_t mip_level = 0,
132  uint32_t slice = 0,
133  bool convert_to_read = true);
134 
135  //----------------------------------------------------------------------------
136  /// @brief Record a command to generate all mip levels for a texture.
137  ///
138  /// @param[in] texture The texture to generate mipmaps for.
139  /// @param[in] label The optional debug label to give the command.
140  ///
141  /// @return If the command was valid for subsequent commitment.
142  ///
143  bool GenerateMipmap(std::shared_ptr<Texture> texture,
144  std::string_view label = "");
145 
146  //----------------------------------------------------------------------------
147  /// @brief Encode the recorded commands to the underlying command buffer.
148  ///
149  /// @return If the commands were encoded to the underlying command
150  /// buffer.
151  ///
152  virtual bool EncodeCommands() const = 0;
153 
154  protected:
155  explicit BlitPass();
156 
157  virtual void OnSetLabel(std::string_view label) = 0;
158 
160  std::shared_ptr<Texture> source,
161  std::shared_ptr<Texture> destination,
162  IRect source_region,
163  IPoint destination_origin,
164  std::string_view label) = 0;
165 
167  std::shared_ptr<Texture> source,
168  std::shared_ptr<DeviceBuffer> destination,
169  IRect source_region,
170  size_t destination_offset,
171  std::string_view label) = 0;
172 
174  BufferView source,
175  std::shared_ptr<Texture> destination,
176  IRect destination_region,
177  std::string_view label,
178  uint32_t mip_level,
179  uint32_t slice,
180  bool convert_to_read) = 0;
181 
182  virtual bool OnGenerateMipmapCommand(std::shared_ptr<Texture> texture,
183  std::string_view label) = 0;
184 
185  private:
186  BlitPass(const BlitPass&) = delete;
187 
188  BlitPass& operator=(const BlitPass&) = delete;
189 };
190 
191 } // namespace impeller
192 
193 #endif // FLUTTER_IMPELLER_RENDERER_BLIT_PASS_H_
Blit passes encode blit into the underlying command buffer.
Definition: blit_pass.h:27
void SetLabel(std::string_view label)
Definition: blit_pass.cc:19
virtual bool EncodeCommands() const =0
Encode the recorded commands to the underlying command buffer.
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 ...
Definition: blit_pass.cc:26
virtual bool ResizeTexture(const std::shared_ptr< Texture > &source, const std::shared_ptr< Texture > &destination)=0
Resize the [source] texture into the [destination] texture.
virtual bool OnCopyTextureToTextureCommand(std::shared_ptr< Texture > source, std::shared_ptr< Texture > destination, IRect source_region, IPoint destination_origin, std::string_view label)=0
bool GenerateMipmap(std::shared_ptr< Texture > texture, std::string_view label="")
Record a command to generate all mip levels for a texture.
Definition: blit_pass.cc:168
virtual bool OnGenerateMipmapCommand(std::shared_ptr< Texture > texture, std::string_view label)=0
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.
Definition: blit_pass.cc:163
virtual bool IsValid() const =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 OnCopyTextureToBufferCommand(std::shared_ptr< Texture > source, std::shared_ptr< DeviceBuffer > destination, IRect source_region, size_t destination_offset, std::string_view label)=0
virtual void OnSetLabel(std::string_view label)=0