Flutter Impeller
render_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_RENDER_PASS_H_
6 #define FLUTTER_IMPELLER_RENDERER_RENDER_PASS_H_
7 
8 #include <cstddef>
9 
10 #include "fml/status.h"
11 #include "impeller/core/formats.h"
18 
19 namespace impeller {
20 
21 //------------------------------------------------------------------------------
22 /// @brief Render passes encode render commands directed as one specific
23 /// render target into an underlying command buffer.
24 ///
25 /// Render passes can be obtained from the command buffer in which
26 /// the pass is meant to encode commands into.
27 ///
28 /// @see `CommandBuffer`
29 ///
30 class RenderPass : public ResourceBinder {
31  public:
32  virtual ~RenderPass();
33 
34  const std::shared_ptr<const Context>& GetContext() const;
35 
36  const RenderTarget& GetRenderTarget() const;
37 
38  ISize GetRenderTargetSize() const;
39 
40  const Matrix& GetOrthographicTransform() const;
41 
42  virtual bool IsValid() const = 0;
43 
44  void SetLabel(std::string_view label);
45 
46  //----------------------------------------------------------------------------
47  /// The pipeline to use for this command.
48  virtual void SetPipeline(PipelineRef pipeline);
49 
50  //----------------------------------------------------------------------------
51  /// The pipeline to use for this command.
52  void SetPipeline(
53  const std::shared_ptr<Pipeline<PipelineDescriptor>>& pipeline);
54 
55  //----------------------------------------------------------------------------
56  /// The debugging label to use for the command.
57  virtual void SetCommandLabel(std::string_view label);
58 
59  //----------------------------------------------------------------------------
60  /// The reference value to use in stenciling operations. Stencil configuration
61  /// is part of pipeline setup and can be read from the pipelines descriptor.
62  ///
63  /// @see `Pipeline`
64  /// @see `PipelineDescriptor`
65  ///
66  virtual void SetStencilReference(uint32_t value);
67 
68  virtual void SetBaseVertex(uint64_t value);
69 
70  //----------------------------------------------------------------------------
71  /// The viewport coordinates that the rasterizer linearly maps normalized
72  /// device coordinates to.
73  /// If unset, the viewport is the size of the render target with a zero
74  /// origin, znear=0, and zfar=1.
75  ///
76  virtual void SetViewport(Viewport viewport);
77 
78  //----------------------------------------------------------------------------
79  /// The scissor rect to use for clipping writes to the render target. The
80  /// scissor rect must lie entirely within the render target.
81  /// If unset, no scissor is applied.
82  ///
83  virtual void SetScissor(IRect scissor);
84 
85  //----------------------------------------------------------------------------
86  /// The number of elements to draw. When only a vertex buffer is set, this is
87  /// the vertex count. When an index buffer is set, this is the index count.
88  ///
89  virtual void SetElementCount(size_t count);
90 
91  //----------------------------------------------------------------------------
92  /// The number of instances of the given set of vertices to render. Not all
93  /// backends support rendering more than one instance at a time.
94  ///
95  /// @warning Setting this to more than one will limit the availability of
96  /// backends to use with this command.
97  ///
98  virtual void SetInstanceCount(size_t count);
99 
100  //----------------------------------------------------------------------------
101  /// @deprecated Use SetVertexBuffer(BufferView[], size_t, size_t) instead.
102  ///
103  /// @brief Specify the vertex and index buffer to use for this command.
104  ///
105  /// @param[in] buffer The vertex and index buffer definition. If possible,
106  /// this value should be moved and not copied.
107  ///
108  /// @return returns if the binding was updated.
109  ///
110  virtual bool SetVertexBuffer(VertexBuffer buffer);
111 
112  //----------------------------------------------------------------------------
113  /// @brief Specify a vertex buffer to use for this command.
114  ///
115  /// @param[in] vertex_buffer The buffer view to use for sourcing vertices.
116  ///
117  /// @return Returns false if the given buffer view is invalid.
118  ///
119  bool SetVertexBuffer(BufferView vertex_buffer);
120 
121  //----------------------------------------------------------------------------
122  /// @brief Specify a set of vertex buffers to use for this command.
123  ///
124  /// @warning This method takes ownership of each buffer view in the vector.
125  /// Attempting to use the given buffer views after this call is
126  /// invalid.
127  ///
128  /// @param[in] vertex_buffers The array of vertex buffer views to use.
129  /// The maximum number of vertex buffers is 16.
130  ///
131  /// @return Returns false if any of the given buffer views are invalid.
132  ///
133  bool SetVertexBuffer(std::vector<BufferView> vertex_buffers);
134 
135  //----------------------------------------------------------------------------
136  /// @brief Specify a set of vertex buffers to use for this command.
137  ///
138  /// @warning This method takes ownership of each buffer view in the vector.
139  /// Attempting to use the given buffer views after this call is
140  /// invalid.
141  ///
142  /// @param[in] vertex_buffers Pointer to an array of vertex buffers to
143  /// be copied. The maximum number of vertex
144  /// buffers is 16.
145  ///
146  /// @param[in] vertex_buffer_count The number of vertex buffers to copy from
147  /// the array (max 16).
148  ///
149  /// @return Returns false if any of the given buffer views are invalid.
150  ///
151  virtual bool SetVertexBuffer(BufferView vertex_buffers[],
152  size_t vertex_buffer_count);
153 
154  //----------------------------------------------------------------------------
155  /// @brief Specify an index buffer to use for this command.
156  /// To unset the index buffer, pass IndexType::kNone to
157  /// index_type.
158  ///
159  /// @param[in] index_buffer The buffer view to use for sourcing indices.
160  /// When an index buffer is bound, the
161  /// `vertex_count` set via `SetVertexBuffer` is used
162  /// as the number of indices to draw.
163  ///
164  /// @param[in] index_type The size of each index in the index buffer. Pass
165  /// IndexType::kNone to unset the index buffer.
166  ///
167  /// @return Returns false if the index buffer view is invalid.
168  ///
169  virtual bool SetIndexBuffer(BufferView index_buffer, IndexType index_type);
170 
171  /// Record the currently pending command.
172  virtual fml::Status Draw();
173 
174  // |ResourceBinder|
175  virtual bool BindResource(ShaderStage stage,
177  const ShaderUniformSlot& slot,
178  const ShaderMetadata* metadata,
179  BufferView view) override;
180 
181  // |ResourceBinder|
182  virtual bool BindResource(ShaderStage stage,
184  const SampledImageSlot& slot,
185  const ShaderMetadata* metadata,
186  std::shared_ptr<const Texture> texture,
187  raw_ptr<const Sampler>) override;
188 
189  /// @brief Bind with dynamically generated shader metadata.
190  virtual bool BindDynamicResource(ShaderStage stage,
192  const SampledImageSlot& slot,
193  std::unique_ptr<ShaderMetadata> metadata,
194  std::shared_ptr<const Texture> texture,
196 
197  /// @brief Bind with dynamically generated shader metadata.
198  virtual bool BindDynamicResource(ShaderStage stage,
200  const ShaderUniformSlot& slot,
201  std::unique_ptr<ShaderMetadata> metadata,
202  BufferView view);
203 
204  //----------------------------------------------------------------------------
205  /// @brief Encode the recorded commands to the underlying command buffer.
206  ///
207  /// @return If the commands were encoded to the underlying command
208  /// buffer.
209  ///
210  bool EncodeCommands() const;
211 
212  //----------------------------------------------------------------------------
213  /// @brief Accessor for the current Commands.
214  ///
215  /// @details Visible for testing.
216  ///
217  virtual const std::vector<Command>& GetCommands() const { return commands_; }
218 
219  //----------------------------------------------------------------------------
220  /// @brief The sample count of the attached render target.
221  SampleCount GetSampleCount() const;
222 
223  //----------------------------------------------------------------------------
224  /// @brief The pixel format of the attached render target.
226 
227  //----------------------------------------------------------------------------
228  /// @brief Whether the render target has a depth attachment.
229  bool HasDepthAttachment() const;
230 
231  //----------------------------------------------------------------------------
232  /// @brief Whether the render target has an stencil attachment.
233  bool HasStencilAttachment() const;
234 
235  protected:
236  const std::shared_ptr<const Context> context_;
237  // The following properties: sample_count, pixel_format,
238  // has_stencil_attachment, and render_target_size are cached on the
239  // RenderTarget to speed up numerous lookups during rendering. This is safe as
240  // the RenderTarget itself is copied into the RenderTarget and only exposed as
241  // a const reference.
248  std::vector<Command> commands_;
249  std::vector<BufferView> vertex_buffers_;
250  std::vector<BufferResource> bound_buffers_;
251  std::vector<TextureAndSampler> bound_textures_;
253 
254  //----------------------------------------------------------------------------
255  /// @brief Record a command for subsequent encoding to the underlying
256  /// command buffer. No work is encoded into the command buffer at
257  /// this time.
258  ///
259  /// @param[in] command The command
260  ///
261  /// @return If the command was valid for subsequent commitment.
262  ///
263  bool AddCommand(Command&& command);
264 
265  RenderPass(std::shared_ptr<const Context> context,
266  const RenderTarget& target);
267 
268  static bool ValidateVertexBuffers(const BufferView vertex_buffers[],
269  size_t vertex_buffer_count);
270 
271  static bool ValidateIndexBuffer(const BufferView& index_buffer,
272  IndexType index_type);
273 
274  virtual void OnSetLabel(std::string_view label) = 0;
275 
276  virtual bool OnEncodeCommands(const Context& context) const = 0;
277 
278  private:
279  RenderPass(const RenderPass&) = delete;
280 
281  RenderPass& operator=(const RenderPass&) = delete;
282 
283  bool BindBuffer(ShaderStage stage,
284  const ShaderUniformSlot& slot,
285  BufferResource resource);
286 
287  bool BindTexture(ShaderStage stage,
288  const SampledImageSlot& slot,
289  TextureResource resource,
291 
292  Command pending_;
293  std::optional<size_t> bound_buffers_start_ = std::nullopt;
294  std::optional<size_t> bound_textures_start_ = std::nullopt;
295  std::optional<size_t> vertex_buffers_start_ = std::nullopt;
296 };
297 
298 } // namespace impeller
299 
300 #endif // FLUTTER_IMPELLER_RENDERER_RENDER_PASS_H_
GLenum type
To do anything rendering related with Impeller, you need a context.
Definition: context.h:65
Render passes encode render commands directed as one specific render target into an underlying comman...
Definition: render_pass.h:30
std::vector< TextureAndSampler > bound_textures_
Definition: render_pass.h:251
virtual bool BindDynamicResource(ShaderStage stage, DescriptorType type, const SampledImageSlot &slot, std::unique_ptr< ShaderMetadata > metadata, std::shared_ptr< const Texture > texture, raw_ptr< const Sampler >)
Bind with dynamically generated shader metadata.
Definition: render_pass.cc:270
const bool has_depth_attachment_
Definition: render_pass.h:244
static bool ValidateIndexBuffer(const BufferView &index_buffer, IndexType index_type)
Definition: render_pass.cc:193
virtual bool SetVertexBuffer(VertexBuffer buffer)
Specify the vertex and index buffer to use for this command.
Definition: render_pass.cc:127
virtual bool BindResource(ShaderStage stage, DescriptorType type, const ShaderUniformSlot &slot, const ShaderMetadata *metadata, BufferView view) override
Definition: render_pass.cc:225
const bool has_stencil_attachment_
Definition: render_pass.h:245
virtual void SetStencilReference(uint32_t value)
Definition: render_pass.cc:103
const RenderTarget & GetRenderTarget() const
Definition: render_pass.cc:43
SampleCount GetSampleCount() const
The sample count of the attached render target.
Definition: render_pass.cc:27
virtual bool SetIndexBuffer(BufferView index_buffer, IndexType index_type)
Specify an index buffer to use for this command. To unset the index buffer, pass IndexType::kNone to ...
Definition: render_pass.cc:164
bool AddCommand(Command &&command)
Record a command for subsequent encoding to the underlying command buffer. No work is encoded into th...
Definition: render_pass.cc:62
const SampleCount sample_count_
Definition: render_pass.h:242
virtual bool OnEncodeCommands(const Context &context) const =0
virtual void SetScissor(IRect scissor)
Definition: render_pass.cc:115
PixelFormat GetRenderTargetPixelFormat() const
The pixel format of the attached render target.
Definition: render_pass.cc:31
const Matrix & GetOrthographicTransform() const
Definition: render_pass.cc:51
RenderPass(std::shared_ptr< const Context > context, const RenderTarget &target)
Definition: render_pass.cc:14
virtual const std::vector< Command > & GetCommands() const
Accessor for the current Commands.
Definition: render_pass.h:217
std::vector< Command > commands_
Definition: render_pass.h:248
const std::shared_ptr< const Context > context_
Definition: render_pass.h:236
std::vector< BufferResource > bound_buffers_
Definition: render_pass.h:250
static bool ValidateVertexBuffers(const BufferView vertex_buffers[], size_t vertex_buffer_count)
Definition: render_pass.cc:174
bool HasStencilAttachment() const
Whether the render target has an stencil attachment.
Definition: render_pass.cc:39
virtual void OnSetLabel(std::string_view label)=0
const Matrix orthographic_
Definition: render_pass.h:252
void SetLabel(std::string_view label)
Definition: render_pass.cc:55
virtual bool IsValid() const =0
std::vector< BufferView > vertex_buffers_
Definition: render_pass.h:249
virtual void SetPipeline(PipelineRef pipeline)
The pipeline to use for this command.
Definition: render_pass.cc:86
const ISize render_target_size_
Definition: render_pass.h:246
ISize GetRenderTargetSize() const
Definition: render_pass.cc:47
virtual void SetInstanceCount(size_t count)
Definition: render_pass.cc:123
virtual fml::Status Draw()
Record the currently pending command.
Definition: render_pass.cc:208
bool HasDepthAttachment() const
Whether the render target has a depth attachment.
Definition: render_pass.cc:35
virtual void SetElementCount(size_t count)
Definition: render_pass.cc:119
virtual void SetCommandLabel(std::string_view label)
The debugging label to use for the command.
Definition: render_pass.cc:97
bool EncodeCommands() const
Encode the recorded commands to the underlying command buffer.
Definition: render_pass.cc:78
const std::shared_ptr< const Context > & GetContext() const
Definition: render_pass.cc:82
virtual void SetBaseVertex(uint64_t value)
Definition: render_pass.cc:107
virtual void SetViewport(Viewport viewport)
Definition: render_pass.cc:111
const RenderTarget render_target_
Definition: render_pass.h:247
const PixelFormat pixel_format_
Definition: render_pass.h:243
int32_t value
PixelFormat
The Pixel formats supported by Impeller. The naming convention denotes the usage of the component,...
Definition: formats.h:99
SampleCount
Definition: formats.h:295
An object used to specify work to the GPU along with references to resources the GPU will used when d...
Definition: command.h:79
A 4x4 matrix using column-major storage.
Definition: matrix.h:37
An interface for binding resources. This is implemented by |Command| and |ComputeCommand| to make GPU...
Metadata required to bind a combined texture and sampler.
Definition: shader_types.h:98
Metadata required to bind a buffer.
Definition: shader_types.h:81