1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
# Coding Style Examples
Detailed examples for the project's C++ coding style.
---
## Core Rules Examples
### Const Placement
```cpp
const T* name // Correct
const T *name // Wrong
```
### Pre-Increment
```cpp
++x // Correct
x++ // Wrong (except when postfix needed)
```
### Operator Spacing
```cpp
x = (a + b) * c; // Correct - spaces around all operators
x=(a+b)*c; // Wrong - no spaces
```
### No Auto (except complex iterators)
```cpp
int count = get_count(); // Correct
auto count = get_count(); // Wrong
for (auto it = map.begin(); ...) // OK - complex iterator type
```
### No C++ Casts
```cpp
(int)value // Correct
static_cast<int>(value) // Wrong
```
---
## Preprocessor Style
```cpp
#if defined(MY_TAG)
// code here
#endif /* defined(MY_TAG) */
```
Always use `defined()` and closing comment.
---
## Platform-Specific Code
**Rule:** Platform-specific compilation (`#ifdef DEMO_CROSS_COMPILE_WIN32`, etc.) must be confined to `src/gpu/gpu.{h,cc}` and `src/platform/platform.{h,cc}`.
### Correct
```cpp
// In gpu.h - abstract platform differences
#if defined(DEMO_CROSS_COMPILE_WIN32)
using GpuTextureCopyInfo = WGPUImageCopyTexture;
#else
using GpuTextureCopyInfo = WGPUTexelCopyTextureInfo;
#endif
// In effect.cc - use abstraction
GpuTextureCopyInfo src_copy = {
.texture = src, .mipLevel = 0, .origin = {0, 0, 0}};
```
### Wrong
```cpp
// In effect.cc - direct platform check (FORBIDDEN)
#if defined(DEMO_CROSS_COMPILE_WIN32)
WGPUImageCopyTexture src_copy = {...};
#else
WGPUTexelCopyTextureInfo src_copy = {...};
#endif
```
**Rationale:**
- Centralizes platform handling in gpu/platform layers
- Prevents #ifdef proliferation across codebase
- Makes cross-platform testing easier
---
## Struct Initialization
### Good
```cpp
const WGPUDescriptor desc = {
.format = g_format,
.dimension = WGPUTextureViewDimension_2D,
};
```
### Bad
```cpp
WGPUDescriptor desc = {};
desc.format = g_format;
desc.dimension = WGPUTextureViewDimension_2D;
```
Use designated initializers, not field-by-field assignment.
---
## Class Keywords Indentation
```cpp
class MyClass {
public: // 1 space indent
void foo();
private: // 1 space indent
int field_;
};
```
---
## Comments
### Function Comments
```cpp
// Initializes the audio engine with default settings.
void audio_init() {
...
}
```
One-line comment for non-obvious functions.
### File Headers
```cpp
// demo64k - 64 kilobyte demo
// src/audio/synth.cc
// Audio synthesis engine
```
Three-line header for all source files.
---
## WGSL Shader Style
### Return vs Pointer Parameters
**Rule:** Prefer return values over pointer parameters for small structs (≤16 bytes).
```wgsl
// Correct - return value (12 bytes: 3×f32)
fn rayMarchWithID(ro: vec3<f32>, rd: vec3<f32>, init: RayMarchResult) -> RayMarchResult {
var result = init;
// ... modify result
return result;
}
// Wrong - pointer parameter (unnecessary complexity)
fn rayMarchWithID(ro: vec3<f32>, rd: vec3<f32>, result: ptr<function, RayMarchResult>) {
// ... modify *result
}
```
**Rationale:**
- Small structs (≤16 bytes) are efficiently handled by GPU return value optimization
- Functional style is clearer and less error-prone
- `ptr<function, T>` adds complexity with no performance gain for small types
---
## WGPU Object Initialization
**Rule:** Initialization of `WGPU...` objects should leverage `gpu.h` function helpers as much as possible.
### Correct
```cpp
// In an effect file
WGPURenderPassColorAttachment color_attachment = {};
gpu_init_color_attachment(color_attachment, output_view);
```
### Wrong
```cpp
// In an effect file
WGPURenderPassColorAttachment color_attachment = {};
color_attachment.view = output_view;
color_attachment.loadOp = WGPULoadOp_Clear;
color_attachment.storeOp = WGPUStoreOp_Store;
color_attachment.clearValue = {0.0f, 0.0f, 0.0f, 1.0f};
#if !defined(DEMO_CROSS_COMPILE_WIN32)
color_attachment.depthSlice = WGPU_DEPTH_SLICE_UNDEFINED;
#endif
```
**Rationale:**
- Centralizes platform-specific initialization logic (e.g., `depthSlice`).
- Reduces boilerplate code in effects and other rendering code.
- Ensures consistent and correct initialization across the codebase.
|
