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