| Flutter Impeller |

command.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 #pragma once
6
7 #include <map>
8 #include <memory>
9 #include <optional>
10 #include <string>
11
12 #include "flutter/fml/logging.h"
13 #include "flutter/fml/macros.h"
14 #include "impeller/core/buffer_view.h"
15 #include "impeller/core/formats.h"
16 #include "impeller/core/resource_binder.h"
17 #include "impeller/core/sampler.h"
18 #include "impeller/core/shader_types.h"
19 #include "impeller/core/texture.h"
20 #include "impeller/core/vertex_buffer.h"
21 #include "impeller/geometry/rect.h"
22 #include "impeller/renderer/pipeline.h"
23 #include "impeller/renderer/vertex_buffer_builder.h"
24 #include "impeller/tessellator/tessellator.h"
25
26 namespace impeller {
27
28 #ifdef IMPELLER_DEBUG
29 #define DEBUG_COMMAND_INFO(obj, arg) obj.label = arg;
30 #else
31 #define DEBUG_COMMAND_INFO(obj, arg)
32 #endif // IMPELLER_DEBUG
33
34 template <class T>
35 struct Resource {
36 using ResourceType = T;
37 ResourceType resource;
38
39 Resource() {}
40
41 Resource(const ShaderMetadata* metadata, ResourceType p_resource)
42 : resource(p_resource), metadata_(metadata) {}
43
44 Resource(std::shared_ptr<const ShaderMetadata>& metadata,
45 ResourceType p_resource)
46 : resource(p_resource), dynamic_metadata_(metadata) {}
47
48 const ShaderMetadata* GetMetadata() const {
49 return dynamic_metadata_ ? dynamic_metadata_.get() : metadata_;
50 }
51
52 private:
53 // Static shader metadata (typically generated by ImpellerC).
54 const ShaderMetadata* metadata_ = nullptr;
55
56 // Dynamically generated shader metadata.
57 std::shared_ptr<const ShaderMetadata> dynamic_metadata_;
58 };
59
60 using BufferResource = Resource<BufferView>;
61 using TextureResource = Resource<std::shared_ptr<const Texture>>;
62 using SamplerResource = Resource<std::shared_ptr<const Sampler>>;
63
64 /// @brief combines the texture, sampler and sampler slot information.
65 struct TextureAndSampler {
66 SampledImageSlot slot;
67 TextureResource texture;
68 SamplerResource sampler;
69 };
70
71 /// @brief combines the buffer resource and its uniform slot information.
72 struct BufferAndUniformSlot {
73 ShaderUniformSlot slot;
74 BufferResource view;
75 };
76
77 struct Bindings {
78 std::map<size_t, TextureAndSampler> sampled_images;
79 std::map<size_t, BufferAndUniformSlot> buffers;
80 // This is only valid for vertex bindings.
81 BufferAndUniformSlot vertex_buffer;
82 };
83
84 //------------------------------------------------------------------------------
85 /// @brief An object used to specify work to the GPU along with references
86 /// to resources the GPU will used when doing said work.
87 ///
88 /// To construct a valid command, follow these steps:
89 /// * Specify a valid pipeline.
90 /// * Specify vertex information via a call `BindVertices`
91 /// * Specify any stage bindings.
92 /// * (Optional) Specify a debug label.
93 ///
94 /// Command are very lightweight objects and can be created
95 /// frequently and on demand. The resources referenced in commands
96 /// views into buffers managed by other allocators and resource
97 /// managers.
98 ///
99 struct Command : public ResourceBinder {
100 //----------------------------------------------------------------------------
101 /// The pipeline to use for this command.
102 ///
103 std::shared_ptr<Pipeline<PipelineDescriptor>> pipeline;
104 //----------------------------------------------------------------------------
105 /// The buffer, texture, and sampler bindings used by the vertex pipeline
106 /// stage.
107 ///
108 Bindings vertex_bindings;
109 //----------------------------------------------------------------------------
110 /// The buffer, texture, and sampler bindings used by the fragment pipeline
111 /// stage.
112 ///
113 Bindings fragment_bindings;
114 //----------------------------------------------------------------------------
115 /// The index buffer binding used by the vertex shader stage. Instead of
116 /// setting this directly, it usually easier to specify the vertex and index
117 /// buffer bindings directly via a single call to `BindVertices`.
118 ///
119 /// @see `BindVertices`
120 ///
121 BufferView index_buffer;
122 //----------------------------------------------------------------------------
123 /// The number of vertices to draw.
124 ///
125 /// If the index_type is `IndexType::kNone`, this is a count into the vertex
126 /// buffer. Otherwise, it is a count into the index buffer. Set the vertex and
127 /// index buffers as well as the index count using a call to `BindVertices`.
128 ///
129 /// @see `BindVertices`
130 ///
131 size_t vertex_count = 0u;
132 //----------------------------------------------------------------------------
133 /// The type of indices in the index buffer. The indices must be tightly
134 /// packed in the index buffer.
135 ///
136 IndexType index_type = IndexType::kUnknown;
137
138 #ifdef IMPELLER_DEBUG
139 //----------------------------------------------------------------------------
140 /// The debugging label to use for the command.
141 ///
142 std::string label;
143 #endif // IMPELLER_DEBUG
144
145 //----------------------------------------------------------------------------
146 /// The reference value to use in stenciling operations. Stencil configuration
147 /// is part of pipeline setup and can be read from the pipelines descriptor.
148 ///
149 /// @see `Pipeline`
150 /// @see `PipelineDescriptor`
151 ///
152 uint32_t stencil_reference = 0u;
153 //----------------------------------------------------------------------------
154 /// The offset used when indexing into the vertex buffer.
155 ///
156 uint64_t base_vertex = 0u;
157 //----------------------------------------------------------------------------
158 /// The viewport coordinates that the rasterizer linearly maps normalized
159 /// device coordinates to.
160 /// If unset, the viewport is the size of the render target with a zero
161 /// origin, znear=0, and zfar=1.
162 ///
163 std::optional<Viewport> viewport;
164 //----------------------------------------------------------------------------
165 /// The scissor rect to use for clipping writes to the render target. The
166 /// scissor rect must lie entirely within the render target.
167 /// If unset, no scissor is applied.
168 ///
169 std::optional<IRect> scissor;
170 //----------------------------------------------------------------------------
171 /// The number of instances of the given set of vertices to render. Not all
172 /// backends support rendering more than one instance at a time.
173 ///
174 /// @warning Setting this to more than one will limit the availability of
175 /// backends to use with this command.
176 ///
177 size_t instance_count = 1u;
178
179 //----------------------------------------------------------------------------
180 /// @brief Specify the vertex and index buffer to use for this command.
181 ///
182 /// @param[in] buffer The vertex and index buffer definition.
183 ///
184 /// @return returns if the binding was updated.
185 ///
186 bool BindVertices(const VertexBuffer& buffer);
187
188 // |ResourceBinder|
189 bool BindResource(ShaderStage stage,
190 const ShaderUniformSlot& slot,
191 const ShaderMetadata& metadata,
192 const BufferView& view) override;
193
194 bool BindResource(ShaderStage stage,
195 const ShaderUniformSlot& slot,
196 const std::shared_ptr<const ShaderMetadata>& metadata,
197 const BufferView& view);
198
199 // |ResourceBinder|
200 bool BindResource(ShaderStage stage,
201 const SampledImageSlot& slot,
202 const ShaderMetadata& metadata,
203 const std::shared_ptr<const Texture>& texture,
204 const std::shared_ptr<const Sampler>& sampler) override;
205
206 BufferView GetVertexBuffer() const;
207
208 constexpr explicit operator bool() const {
209 return pipeline && pipeline->IsValid();
210 }
211
212 private:
213 template <class T>
214 bool DoBindResource(ShaderStage stage,
215 const ShaderUniformSlot& slot,
216 T metadata,
217 const BufferView& view);
218 };
219
220 } // namespace impeller
impeller::Command::vertex_count
size_t vertex_count
Definition: command.h:131
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:99
pipeline.h
impeller::Command::scissor
std::optional< IRect > scissor
Definition: command.h:169
impeller::ShaderUniformSlot
Definition: shader_types.h:81
impeller::Resource::resource
ResourceType resource
Definition: command.h:37
impeller::Command::index_type
IndexType index_type
Definition: command.h:136
vertex_buffer.h
impeller::Resource::Resource
Resource(const ShaderMetadata *metadata, ResourceType p_resource)
Definition: command.h:41
impeller::ShaderMetadata
Definition: shader_types.h:76
impeller::VertexBuffer
Definition: vertex_buffer.h:12
formats.h
impeller::Command::viewport
std::optional< Viewport > viewport
Definition: command.h:163
impeller::ShaderStage
ShaderStage
Definition: shader_types.h:20
impeller::Bindings::buffers
std::map< size_t, BufferAndUniformSlot > buffers
Definition: command.h:79
impeller::Bindings::vertex_buffer
BufferAndUniformSlot vertex_buffer
Definition: command.h:81
impeller::Command::instance_count
size_t instance_count
Definition: command.h:177
sampler.h
impeller::Command::base_vertex
uint64_t base_vertex
Definition: command.h:156
impeller::Command::GetVertexBuffer
BufferView GetVertexBuffer() const
Definition: command.cc:29
impeller::Resource
Definition: command.h:35
tessellator.h
impeller::Resource::Resource
Resource(std::shared_ptr< const ShaderMetadata > &metadata, ResourceType p_resource)
Definition: command.h:44
impeller::Command::vertex_bindings
Bindings vertex_bindings
Definition: command.h:108
resource_binder.h
impeller::ResourceBinder
An interface for binding resources. This is implemented by |Command| and |ComputeCommand| to make GPU...
Definition: resource_binder.h:27
impeller::IndexType
IndexType
Definition: formats.h:320
impeller::SampledImageSlot
Definition: shader_types.h:129
impeller::BufferAndUniformSlot::view
BufferResource view
Definition: command.h:74
impeller::Bindings::sampled_images
std::map< size_t, TextureAndSampler > sampled_images
Definition: command.h:78
impeller::Command::BindResource
bool BindResource(ShaderStage stage, const ShaderUniformSlot &slot, const ShaderMetadata &metadata, const BufferView &view) override
Definition: command.cc:33
impeller::TextureAndSampler::sampler
SamplerResource sampler
Definition: command.h:68
impeller::TextureAndSampler
combines the texture, sampler and sampler slot information.
Definition: command.h:65
impeller::TextureAndSampler::texture
TextureResource texture
Definition: command.h:67
impeller::BufferAndUniformSlot::slot
ShaderUniformSlot slot
Definition: command.h:73
impeller::Command::stencil_reference
uint32_t stencil_reference
Definition: command.h:152
impeller::TextureAndSampler::slot
SampledImageSlot slot
Definition: command.h:66
impeller::BufferView
Definition: buffer_view.h:13
buffer_view.h
impeller::Command::fragment_bindings
Bindings fragment_bindings
Definition: command.h:113
rect.h
texture.h
impeller::Command::BindVertices
bool BindVertices(const VertexBuffer &buffer)
Specify the vertex and index buffer to use for this command.
Definition: command.cc:15
impeller::Command::pipeline
std::shared_ptr< Pipeline< PipelineDescriptor > > pipeline
Definition: command.h:103
impeller::Resource::GetMetadata
const ShaderMetadata * GetMetadata() const
Definition: command.h:48
shader_types.h
impeller
Definition: aiks_context.cc:10
impeller::BufferAndUniformSlot
combines the buffer resource and its uniform slot information.
Definition: command.h:72
impeller::IndexType::kUnknown
@ kUnknown
impeller::Bindings
Definition: command.h:77
vertex_buffer_builder.h
impeller::Command::index_buffer
BufferView index_buffer
Definition: command.h:121
impeller::Resource::Resource
Resource()
Definition: command.h:39