Skip to content

Commit 24838e2

Browse files
committed
Address review: document compute types and tidy style
Adds docstrings to the storage buffer reflection types, the shader bundle schema, ComputePassVK (in doxygen style) and the other types the change adds, and documents the lifetime of the binding returned by Shader::GetStorageBufferAt. Groups the compute limits in Capabilities into a ComputeLimits struct, pops the debug label with a ScopedCleanupClosure, adds argument comments to the Vulkan calls, removes the performance-move-const-arg suppressions and simplifies the binding set lookup in the Flutter GPU compute pass, and builds the test shader bundle descriptions in BUILD.gn from one entry per line.
1 parent 1f36261 commit 24838e2

20 files changed

Lines changed: 275 additions & 297 deletions

‎engine/src/flutter/impeller/compiler/shader_bundle_data.h‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,17 +51,27 @@ class ShaderBundleData {
5151
size_t binding = 0u;
5252
};
5353

54+
/// Reflection data for a storage buffer (an SSBO) that a compute shader
55+
/// declares, serialized as a `ShaderStorageBuffer` in the bundle.
5456
struct ShaderStorageBuffer {
57+
/// The name of the buffer block.
5558
std::string name;
59+
/// The backend's index for the buffer: the Metal buffer index, or the
60+
/// binding on Vulkan. `kOptimizedOutBinding` if the backend compiler
61+
/// removed the buffer because the shader never uses it.
5662
size_t ext_res_0 = 0u;
63+
/// The descriptor set the shader declares the buffer in.
5764
size_t set = 0u;
65+
/// The binding the shader declares the buffer at.
5866
size_t binding = 0u;
67+
/// How the shader accesses the buffer, from its `readonly` or `writeonly`
68+
/// qualifier.
5969
fb::shaderbundle::ShaderResourceAccess access =
6070
fb::shaderbundle::ShaderResourceAccess::kReadWrite;
61-
// The size of the block, counting a trailing runtime-sized array as empty.
71+
/// The size of the block, counting a trailing runtime-sized array as empty.
6272
size_t size_in_bytes = 0u;
63-
// The stride of the block's trailing runtime-sized array, or zero if the
64-
// block does not end in one.
73+
/// The stride of the block's trailing runtime-sized array, or zero if the
74+
/// block does not end in one.
6575
size_t runtime_array_stride = 0u;
6676
};
6777

‎engine/src/flutter/impeller/renderer/backend/gles/capabilities_gles.cc‎

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -428,23 +428,8 @@ bool CapabilitiesGLES::NeedsPartitionedHostBuffer() const {
428428

429429
// The OpenGL ES backend does not support compute, so it reports no compute
430430
// limits.
431-
432-
uint32_t CapabilitiesGLES::GetMaximumComputeWorkgroupInvocations() const {
433-
return 0u;
434-
}
435-
436-
std::array<uint32_t, 3> CapabilitiesGLES::GetMaximumComputeWorkgroupSize()
437-
const {
438-
return {0u, 0u, 0u};
439-
}
440-
441-
std::array<uint32_t, 3> CapabilitiesGLES::GetMaximumComputeWorkgroupCount()
442-
const {
443-
return {0u, 0u, 0u};
444-
}
445-
446-
size_t CapabilitiesGLES::GetMaximumComputeSharedMemorySize() const {
447-
return 0u;
431+
ComputeLimits CapabilitiesGLES::GetComputeLimits() const {
432+
return {};
448433
}
449434

450435
} // namespace impeller

‎engine/src/flutter/impeller/renderer/backend/gles/capabilities_gles.h‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -178,16 +178,7 @@ class CapabilitiesGLES final
178178
bool NeedsPartitionedHostBuffer() const override;
179179

180180
// |Capabilities|
181-
uint32_t GetMaximumComputeWorkgroupInvocations() const override;
182-
183-
// |Capabilities|
184-
std::array<uint32_t, 3> GetMaximumComputeWorkgroupSize() const override;
185-
186-
// |Capabilities|
187-
std::array<uint32_t, 3> GetMaximumComputeWorkgroupCount() const override;
188-
189-
// |Capabilities|
190-
size_t GetMaximumComputeSharedMemorySize() const override;
181+
ComputeLimits GetComputeLimits() const override;
191182

192183
private:
193184
bool supports_texture_to_texture_blits_ = false;

‎engine/src/flutter/impeller/renderer/backend/metal/compute_pass_mtl.mm‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -142,15 +142,16 @@
142142
}
143143

144144
fml::Status ComputePassMTL::Compute(std::array<uint32_t, 3> workgroup_count) {
145+
// The label set by `SetCommandLabel` applies to this dispatch only.
146+
fml::ScopedCleanupClosure pop_label([this]() { PopCommandLabel(); });
147+
145148
// A dispatch with no workgroups does nothing, like a draw with no vertices.
146149
if (workgroup_count[0] == 0u || workgroup_count[1] == 0u ||
147150
workgroup_count[2] == 0u) {
148-
PopCommandLabel();
149151
return fml::Status();
150152
}
151153

152154
if (!pass_bindings_cache_.GetPipeline()) {
153-
PopCommandLabel();
154155
return fml::Status(fml::StatusCode::kCancelled,
155156
"No compute pipeline is bound.");
156157
}
@@ -165,8 +166,6 @@
165166
dispatchThreadgroups:MTLSizeMake(workgroup_count[0], workgroup_count[1],
166167
workgroup_count[2])
167168
threadsPerThreadgroup:threads_per_threadgroup];
168-
169-
PopCommandLabel();
170169
return fml::Status();
171170
}
172171

‎engine/src/flutter/impeller/renderer/backend/metal/context_mtl.mm‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -71,15 +71,23 @@ static bool DeviceSupportsTextureCompressionAstcHdr(id<MTLDevice> device) {
7171
return [device supportsFamily:MTLGPUFamilyApple6];
7272
}
7373

74-
// Metal reports the threadgroup size limit per dimension. The limit on the
75-
// total number of threads in a threadgroup equals the x limit on every Metal
76-
// GPU family (1024, or 512 before A11). A pipeline can lower it further, which
77-
// pipeline creation checks.
78-
static std::array<uint32_t, 3> DeviceMaxThreadsPerThreadgroup(
79-
id<MTLDevice> device) {
74+
static ComputeLimits InferMetalComputeLimits(id<MTLDevice> device) {
8075
const MTLSize size = device.maxThreadsPerThreadgroup;
81-
return {static_cast<uint32_t>(size.width), static_cast<uint32_t>(size.height),
82-
static_cast<uint32_t>(size.depth)};
76+
return ComputeLimits{
77+
// The limit on the total number of threads in a threadgroup equals the
78+
// x limit on every Metal GPU family (1024, or 512 before A11). A
79+
// pipeline can lower it further, which pipeline creation checks.
80+
.max_workgroup_invocations = static_cast<uint32_t>(size.width),
81+
.max_workgroup_size = {static_cast<uint32_t>(size.width),
82+
static_cast<uint32_t>(size.height),
83+
static_cast<uint32_t>(size.depth)},
84+
// Metal does not limit the threadgroup count of a dispatch beyond the
85+
// 32-bit grid coordinates a shader sees.
86+
.max_workgroup_count = {std::numeric_limits<uint32_t>::max(),
87+
std::numeric_limits<uint32_t>::max(),
88+
std::numeric_limits<uint32_t>::max()},
89+
.max_shared_memory_size = device.maxThreadgroupMemoryLength,
90+
};
8391
}
8492

8593
static std::unique_ptr<Capabilities> InferMetalCapabilities(
@@ -117,15 +125,7 @@ static bool DeviceSupportsTextureCompressionAstcHdr(id<MTLDevice> device) {
117125
.SetSupportsTextureCompression(
118126
CompressedTextureFamily::kASTCHDR,
119127
DeviceSupportsTextureCompressionAstcHdr(device))
120-
.SetMaximumComputeWorkgroupInvocations(
121-
DeviceMaxThreadsPerThreadgroup(device)[0])
122-
.SetMaximumComputeWorkgroupSize(DeviceMaxThreadsPerThreadgroup(device))
123-
// Metal does not limit the threadgroup count of a dispatch beyond the
124-
// 32-bit grid coordinates a shader sees.
125-
.SetMaximumComputeWorkgroupCount({std::numeric_limits<uint32_t>::max(),
126-
std::numeric_limits<uint32_t>::max(),
127-
std::numeric_limits<uint32_t>::max()})
128-
.SetMaximumComputeSharedMemorySize(device.maxThreadgroupMemoryLength)
128+
.SetComputeLimits(InferMetalComputeLimits(device))
129129
#if FML_OS_IOS && !TARGET_OS_SIMULATOR
130130
.SetMinimumUniformAlignment(16)
131131
#else

‎engine/src/flutter/impeller/renderer/backend/vulkan/capabilities_vk.cc‎

Lines changed: 12 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -814,23 +814,18 @@ bool CapabilitiesVK::NeedsPartitionedHostBuffer() const {
814814
return false;
815815
}
816816

817-
uint32_t CapabilitiesVK::GetMaximumComputeWorkgroupInvocations() const {
818-
return device_properties_.limits.maxComputeWorkGroupInvocations;
819-
}
820-
821-
std::array<uint32_t, 3> CapabilitiesVK::GetMaximumComputeWorkgroupSize() const {
822-
const auto& size = device_properties_.limits.maxComputeWorkGroupSize;
823-
return {size[0], size[1], size[2]};
824-
}
825-
826-
std::array<uint32_t, 3> CapabilitiesVK::GetMaximumComputeWorkgroupCount()
827-
const {
828-
const auto& count = device_properties_.limits.maxComputeWorkGroupCount;
829-
return {count[0], count[1], count[2]};
830-
}
831-
832-
size_t CapabilitiesVK::GetMaximumComputeSharedMemorySize() const {
833-
return device_properties_.limits.maxComputeSharedMemorySize;
817+
ComputeLimits CapabilitiesVK::GetComputeLimits() const {
818+
const vk::PhysicalDeviceLimits& limits = device_properties_.limits;
819+
return ComputeLimits{
820+
.max_workgroup_invocations = limits.maxComputeWorkGroupInvocations,
821+
.max_workgroup_size = {limits.maxComputeWorkGroupSize[0],
822+
limits.maxComputeWorkGroupSize[1],
823+
limits.maxComputeWorkGroupSize[2]},
824+
.max_workgroup_count = {limits.maxComputeWorkGroupCount[0],
825+
limits.maxComputeWorkGroupCount[1],
826+
limits.maxComputeWorkGroupCount[2]},
827+
.max_shared_memory_size = limits.maxComputeSharedMemorySize,
828+
};
834829
}
835830

836831
bool CapabilitiesVK::HasExtension(RequiredCommonDeviceExtensionVK ext) const {

‎engine/src/flutter/impeller/renderer/backend/vulkan/capabilities_vk.h‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -317,16 +317,7 @@ class CapabilitiesVK final : public Capabilities,
317317
bool NeedsPartitionedHostBuffer() const override;
318318

319319
// |Capabilities|
320-
uint32_t GetMaximumComputeWorkgroupInvocations() const override;
321-
322-
// |Capabilities|
323-
std::array<uint32_t, 3> GetMaximumComputeWorkgroupSize() const override;
324-
325-
// |Capabilities|
326-
std::array<uint32_t, 3> GetMaximumComputeWorkgroupCount() const override;
327-
328-
// |Capabilities|
329-
size_t GetMaximumComputeSharedMemorySize() const override;
320+
ComputeLimits GetComputeLimits() const override;
330321

331322
//----------------------------------------------------------------------------
332323
/// @return If fixed-rate compression for non-onscreen surfaces is

‎engine/src/flutter/impeller/renderer/backend/vulkan/compute_pass_vk.cc‎

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
#include <vector>
88

9+
#include "flutter/fml/closure.h"
910
#include "flutter/fml/logging.h"
1011
#include "impeller/renderer/backend/vulkan/command_buffer_vk.h"
1112
#include "impeller/renderer/backend/vulkan/compute_pipeline_vk.h"
@@ -148,36 +149,35 @@ fml::Status ComputePassVK::BindDescriptorSet() {
148149
context_vk.GetDevice().updateDescriptorSets(writes.size(), writes.data(), 0u,
149150
{});
150151
command_buffer_->GetCommandBuffer().bindDescriptorSets(
151-
vk::PipelineBindPoint::eCompute, // bind point
152-
pipeline_vk.GetPipelineLayout(), // layout
153-
0, // first set
154-
1, // set count
155-
&descriptor_set, // sets
156-
0, // offset count
157-
nullptr // offsets
158-
);
152+
/*pipelineBindPoint=*/vk::PipelineBindPoint::eCompute,
153+
/*layout=*/pipeline_vk.GetPipelineLayout(),
154+
/*firstSet=*/0,
155+
/*descriptorSetCount=*/1,
156+
/*pDescriptorSets=*/&descriptor_set,
157+
/*dynamicOffsetCount=*/0,
158+
/*pDynamicOffsets=*/nullptr);
159159
descriptor_set_dirty_ = false;
160160
return fml::Status();
161161
}
162162

163163
// |ComputePass|
164164
fml::Status ComputePassVK::Compute(std::array<uint32_t, 3> workgroup_count) {
165+
// The label set by `SetCommandLabel` applies to this dispatch only.
166+
fml::ScopedCleanupClosure pop_label([this]() { PopCommandLabel(); });
167+
165168
// A dispatch with no workgroups does nothing, like a draw with no vertices.
166169
if (workgroup_count[0] == 0u || workgroup_count[1] == 0u ||
167170
workgroup_count[2] == 0u) {
168-
PopCommandLabel();
169171
return fml::Status();
170172
}
171173

172174
if (!pipeline_) {
173-
PopCommandLabel();
174175
return fml::Status(fml::StatusCode::kCancelled,
175176
"No compute pipeline is bound.");
176177
}
177178

178179
if (descriptor_set_dirty_) {
179-
if (auto status = BindDescriptorSet(); !status.ok()) {
180-
PopCommandLabel();
180+
if (fml::Status status = BindDescriptorSet(); !status.ok()) {
181181
return status;
182182
}
183183
}
@@ -212,8 +212,6 @@ fml::Status ComputePassVK::Compute(std::array<uint32_t, 3> workgroup_count) {
212212
// directly.
213213
command_buffer_->GetCommandBuffer().dispatch(
214214
workgroup_count[0], workgroup_count[1], workgroup_count[2]);
215-
216-
PopCommandLabel();
217215
return fml::Status();
218216
}
219217

‎engine/src/flutter/impeller/renderer/backend/vulkan/compute_pass_vk.h‎

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,11 @@ namespace impeller {
1616

1717
class CommandBufferVK;
1818

19+
/// A compute pass that records dispatches into a Vulkan command buffer.
20+
///
21+
/// The first dispatch waits on the writes of earlier render and blit passes,
22+
/// each later dispatch waits on the one before it, and encoding the pass makes
23+
/// its writes visible to later work, so callers need no manual barriers.
1924
class ComputePassVK final : public ComputePass {
2025
public:
2126
// |ComputePass|
@@ -24,27 +29,36 @@ class ComputePassVK final : public ComputePass {
2429
private:
2530
friend class CommandBufferVK;
2631

27-
// A resource bound to one binding index of the pass.
32+
/// A resource bound to one binding index of the pass.
2833
struct BoundResource {
34+
/// The descriptor type the resource is bound as.
2935
DescriptorType type;
36+
/// Set for a uniform or storage buffer.
3037
std::optional<vk::DescriptorBufferInfo> buffer_info;
38+
/// Set for a sampled image.
3139
std::optional<vk::DescriptorImageInfo> image_info;
3240
};
3341

42+
/// The command buffer the pass records into.
3443
std::shared_ptr<CommandBufferVK> command_buffer_;
3544
std::string label_;
3645
bool is_valid_ = false;
3746

38-
// The pipeline and bindings persist across dispatches in the pass.
47+
/// The pipeline of later dispatches. It persists across dispatches in the
48+
/// pass until replaced.
3949
std::shared_ptr<Pipeline<ComputePipelineDescriptor>> pipeline_;
50+
/// The resources of later dispatches, keyed by binding index. They persist
51+
/// across dispatches in the pass until replaced.
4052
absl::flat_hash_map<uint32_t, BoundResource> bindings_;
41-
// Whether the pipeline or a binding changed since the last dispatch, so the
42-
// next dispatch needs a new descriptor set. A descriptor set that an earlier
43-
// dispatch in this command buffer uses is never rewritten.
53+
/// Whether the pipeline or a binding changed since the last dispatch, so the
54+
/// next dispatch needs a new descriptor set. A descriptor set that an earlier
55+
/// dispatch in this command buffer uses is never rewritten.
4456
bool descriptor_set_dirty_ = true;
45-
// Whether a dispatch was recorded. The first dispatch waits on earlier
46-
// render and blit passes, and each later one on the dispatch before it.
57+
/// Whether a dispatch was recorded. The first dispatch waits on earlier
58+
/// render and blit passes, and each later one on the dispatch before it.
4759
bool has_dispatched_ = false;
60+
/// Whether `SetCommandLabel` pushed a debug group that the next dispatch
61+
/// pops.
4862
bool has_label_ = false;
4963

5064
ComputePassVK(std::shared_ptr<const Context> context,
@@ -90,12 +104,15 @@ class ComputePassVK final : public ComputePass {
90104
std::shared_ptr<const Texture> texture,
91105
raw_ptr<const Sampler> sampler) override;
92106

107+
/// Binds a uniform or storage buffer view at `binding` for later
108+
/// dispatches. Returns false if the view has no buffer.
93109
bool BindResource(size_t binding, DescriptorType type, BufferView view);
94110

95-
// Allocates, writes and binds a descriptor set for the current pipeline and
96-
// bindings.
111+
/// Allocates, writes and binds a descriptor set for the current pipeline and
112+
/// bindings.
97113
fml::Status BindDescriptorSet();
98114

115+
/// Pops the debug group pushed by `SetCommandLabel`, if any.
99116
void PopCommandLabel();
100117
};
101118

0 commit comments

Comments
 (0)