| 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"
12 #include "impeller/core/resource_binder.h"
13 #include "impeller/core/shader_types.h"
14 #include "impeller/core/vertex_buffer.h"
15 #include "impeller/renderer/command.h"
16 #include "impeller/renderer/command_buffer.h"
17 #include "impeller/renderer/render_target.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,
176 DescriptorType type,
177 const ShaderUniformSlot& slot,
178 const ShaderMetadata* metadata,
179 BufferView view) override;
180
181 // |ResourceBinder|
182 virtual bool BindResource(ShaderStage stage,
183 DescriptorType type,
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,
191 DescriptorType type,
192 const SampledImageSlot& slot,
193 std::unique_ptr<ShaderMetadata> metadata,
194 std::shared_ptr<const Texture> texture,
195 raw_ptr<const Sampler>);
196
197 /// @brief Bind with dynamically generated shader metadata.
198 virtual bool BindDynamicResource(ShaderStage stage,
199 DescriptorType type,
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.
225 PixelFormat GetRenderTargetPixelFormat() const;
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.
242 const SampleCount sample_count_;
243 const PixelFormat pixel_format_;
244 const bool has_depth_attachment_;
245 const bool has_stencil_attachment_;
246 const ISize render_target_size_;
247 const RenderTarget render_target_;
248 std::vector<Command> commands_;
249 std::vector<BufferView> vertex_buffers_;
250 std::vector<BufferResource> bound_buffers_;
251 std::vector<TextureAndSampler> bound_textures_;
252 const Matrix orthographic_;
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,
290 raw_ptr<const Sampler>);
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_
type
GLenum type
Definition: blit_command_gles.cc:151
impeller::Context
To do anything rendering related with Impeller, you need a context.
Definition: context.h:47
impeller::Pipeline< PipelineDescriptor >
impeller::RenderPass
Render passes encode render commands directed as one specific render target into an underlying comman...
Definition: render_pass.h:30
impeller::RenderPass::bound_textures_
std::vector< TextureAndSampler > bound_textures_
Definition: render_pass.h:251
impeller::RenderPass::BindDynamicResource
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
impeller::RenderPass::has_depth_attachment_
const bool has_depth_attachment_
Definition: render_pass.h:244
impeller::RenderPass::ValidateIndexBuffer
static bool ValidateIndexBuffer(const BufferView &index_buffer, IndexType index_type)
Definition: render_pass.cc:193
impeller::RenderPass::SetVertexBuffer
virtual bool SetVertexBuffer(VertexBuffer buffer)
Specify the vertex and index buffer to use for this command.
Definition: render_pass.cc:127
impeller::RenderPass::BindResource
virtual bool BindResource(ShaderStage stage, DescriptorType type, const ShaderUniformSlot &slot, const ShaderMetadata *metadata, BufferView view) override
Definition: render_pass.cc:225
impeller::RenderPass::has_stencil_attachment_
const bool has_stencil_attachment_
Definition: render_pass.h:245
impeller::RenderPass::SetStencilReference
virtual void SetStencilReference(uint32_t value)
Definition: render_pass.cc:103
impeller::RenderPass::GetRenderTarget
const RenderTarget & GetRenderTarget() const
Definition: render_pass.cc:43
impeller::RenderPass::GetSampleCount
SampleCount GetSampleCount() const
The sample count of the attached render target.
Definition: render_pass.cc:27
impeller::RenderPass::SetIndexBuffer
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
impeller::RenderPass::AddCommand
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
impeller::RenderPass::sample_count_
const SampleCount sample_count_
Definition: render_pass.h:242
impeller::RenderPass::OnEncodeCommands
virtual bool OnEncodeCommands(const Context &context) const =0
impeller::RenderPass::SetScissor
virtual void SetScissor(IRect scissor)
Definition: render_pass.cc:115
impeller::RenderPass::GetRenderTargetPixelFormat
PixelFormat GetRenderTargetPixelFormat() const
The pixel format of the attached render target.
Definition: render_pass.cc:31
impeller::RenderPass::GetOrthographicTransform
const Matrix & GetOrthographicTransform() const
Definition: render_pass.cc:51
impeller::RenderPass::RenderPass
RenderPass(std::shared_ptr< const Context > context, const RenderTarget &target)
Definition: render_pass.cc:14
impeller::RenderPass::GetCommands
virtual const std::vector< Command > & GetCommands() const
Accessor for the current Commands.
Definition: render_pass.h:217
impeller::RenderPass::commands_
std::vector< Command > commands_
Definition: render_pass.h:248
impeller::RenderPass::context_
const std::shared_ptr< const Context > context_
Definition: render_pass.h:236
impeller::RenderPass::~RenderPass
virtual ~RenderPass()
Definition: render_pass.cc:25
impeller::RenderPass::bound_buffers_
std::vector< BufferResource > bound_buffers_
Definition: render_pass.h:250
impeller::RenderPass::ValidateVertexBuffers
static bool ValidateVertexBuffers(const BufferView vertex_buffers[], size_t vertex_buffer_count)
Definition: render_pass.cc:174
impeller::RenderPass::HasStencilAttachment
bool HasStencilAttachment() const
Whether the render target has an stencil attachment.
Definition: render_pass.cc:39
impeller::RenderPass::OnSetLabel
virtual void OnSetLabel(std::string_view label)=0
impeller::RenderPass::orthographic_
const Matrix orthographic_
Definition: render_pass.h:252
impeller::RenderPass::SetLabel
void SetLabel(std::string_view label)
Definition: render_pass.cc:55
impeller::RenderPass::IsValid
virtual bool IsValid() const =0
impeller::RenderPass::vertex_buffers_
std::vector< BufferView > vertex_buffers_
Definition: render_pass.h:249
impeller::RenderPass::SetPipeline
virtual void SetPipeline(PipelineRef pipeline)
The pipeline to use for this command.
Definition: render_pass.cc:86
impeller::RenderPass::render_target_size_
const ISize render_target_size_
Definition: render_pass.h:246
impeller::RenderPass::GetRenderTargetSize
ISize GetRenderTargetSize() const
Definition: render_pass.cc:47
impeller::RenderPass::SetInstanceCount
virtual void SetInstanceCount(size_t count)
Definition: render_pass.cc:123
impeller::RenderPass::Draw
virtual fml::Status Draw()
Record the currently pending command.
Definition: render_pass.cc:208
impeller::RenderPass::HasDepthAttachment
bool HasDepthAttachment() const
Whether the render target has a depth attachment.
Definition: render_pass.cc:35
impeller::RenderPass::SetElementCount
virtual void SetElementCount(size_t count)
Definition: render_pass.cc:119
impeller::RenderPass::SetCommandLabel
virtual void SetCommandLabel(std::string_view label)
The debugging label to use for the command.
Definition: render_pass.cc:97
impeller::RenderPass::EncodeCommands
bool EncodeCommands() const
Encode the recorded commands to the underlying command buffer.
Definition: render_pass.cc:78
impeller::RenderPass::GetContext
const std::shared_ptr< const Context > & GetContext() const
Definition: render_pass.cc:82
impeller::RenderPass::SetBaseVertex
virtual void SetBaseVertex(uint64_t value)
Definition: render_pass.cc:107
impeller::RenderPass::SetViewport
virtual void SetViewport(Viewport viewport)
Definition: render_pass.cc:111
impeller::RenderPass::render_target_
const RenderTarget render_target_
Definition: render_pass.h:247
impeller::RenderPass::pixel_format_
const PixelFormat pixel_format_
Definition: render_pass.h:243
impeller::RenderTarget
Definition: render_target.h:38
impeller::Resource
Definition: command.h:24
impeller::raw_ptr< Pipeline< PipelineDescriptor > >
command.h
command_buffer.h
formats.h
value
int32_t value
Definition: dl_golden_unittests.cc:459
impeller
Definition: allocation.cc:12
impeller::IndexType
IndexType
Definition: formats.h:343
impeller::PixelFormat
PixelFormat
The Pixel formats supported by Impeller. The naming convention denotes the usage of the component,...
Definition: formats.h:99
impeller::ShaderStage
ShaderStage
Definition: shader_types.h:22
impeller::DescriptorType
DescriptorType
Definition: shader_types.h:158
impeller::SampleCount
SampleCount
Definition: formats.h:295
render_target.h
resource_binder.h
shader_types.h
impeller::BufferView
Definition: buffer_view.h:19
impeller::Command
An object used to specify work to the GPU along with references to resources the GPU will used when d...
Definition: command.h:79
impeller::Matrix
A 4x4 matrix using column-major storage.
Definition: matrix.h:37
impeller::ResourceBinder
An interface for binding resources. This is implemented by |Command| and |ComputeCommand| to make GPU...
Definition: resource_binder.h:24
impeller::SampledImageSlot
Metadata required to bind a combined texture and sampler.
Definition: shader_types.h:98
impeller::ShaderMetadata
Definition: shader_types.h:72
impeller::ShaderUniformSlot
Metadata required to bind a buffer.
Definition: shader_types.h:81
impeller::TRect
Definition: rect.h:122
impeller::TSize
Definition: size.h:25
impeller::VertexBuffer
Definition: vertex_buffer.h:15
impeller::Viewport
Definition: formats.h:403
vertex_buffer.h