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
|
# Contributing Guidelines
This document outlines the conventions to follow when contributing to this project.
## Commit Policy
### Verify Build and Tests Before Committing
Before preparing or proposing a commit, you **must** perform the following verifications to prevent regressions:
1. **MacOS / Linux (Native)**:
* Build the project (debug or release).
* Run the entire test suite (`ctest`).
* Ensure all tests pass.
2. **Windows (Cross-Compilation)**:
* If `mingw-w64` is installed on your system, you **must** also verify the Windows build.
* Run `./scripts/build_win.sh`.
* Ensure the build succeeds and produces the `demo64k_packed.exe` binary.
* Check the size report to ensure no unexpected bloat.
Refer to the "Testing" and "Windows Cross-Compilation" sections in `HOWTO.md` for detailed instructions.
### Format Code Before Committing
All code **must** be formatted using `clang-format` before committing. This ensures a consistent coding style across the entire codebase.
To format your code, run the following command from the project root:
```bash
clang-format -i $(git ls-files | grep -E '\.(h|cc)$' | grep -vE '^(assets|archive|third_party)/')
```
Refer to the `.clang-format` file in the project root for the specific style rules.
### Ensure Newline at End of File
All source files (`.h`, `.cc`, `.cpp`, etc.) must end with a newline character. This prevents "No newline at end of file" errors from linters and ensures consistent file handling.
### Source File Headers
Every source file (`.h`, `.cc`) must begin with a concise 3-line comment header describing its purpose.
Example:
```cpp
// This file is part of the 64k demo project.
// It implements the core audio synthesis engine.
// This is not a user-facing header, but an internal one.
```
### Function and method comments
Functions and methods, especially if they are internal non user-facing,
should at least have a 1-line comment describing what they do or their
how/when they should be called. Except if they are just 1-line function
or very very short, obvious ones.
### '#endif' directive
The closing #endif directive must recall the corresponding opening #ifdef
clause they are closing
Example:
```cpp
#ifdef MY_TAG
...some code
#endif /* MY TAG */
```
We must also prefer '#if defined(MY_QUITE_LONG_TAG)' over '#ifdef MY_QUITE_LONG_TAG'
especially if there's a risk of having later something like:
```cpp
#if defined(MY_TAG_1) && !defined(MY_TAG_2)
```
### use and abuse 'const' directives
Especially for local variable, use 'const' qualification as much as
possible.
As an example, don't use:
```cpp
StructA variable_name = StructA(...);
```
but prefer instead:
```cpp
const StructA variable_name = StructA(...);
```
if variable_name is not mutated afterward.
Also: pass parameter as "const ref" as much as possible
(```const Struct& param``` instead of pointers or non-const refs)
### put spaces around code and operators (cosmetics)
Don't compact the code to much horizontally, and prefer adding extra
spaces around code and operators.
Example:
```cpp
const bool v = my_variable && (my_function() / 3. > (1. / x));
const y = function_call(3, x, 2.);
for (int x = 0; x < 24; ++x) { ... }
```
instead of
```cpp
const bool v=my_variable&&my_function()/3.>(1./x);
const y = function_call(3,x,2);
for(int x=0;x<24;++x){ ... }
```
### prefer prefixed incrementation over suffixed
Use pre-incrementation:
```cpp
++x
```
instead of post-incrementation:
```cpp
x++
```
### use extra () for boolean operations
Even if they are not strictly needed due to operator precedence rules,
prefer adding extra ()'s around tests for clarity, with parcimony.
### c++ cast
don't use reinterpret_cast<>, static_cast<> or const_cast<>.
### pointer declaration
prefer ```const T* name``` to ```const T *name```.
### 'auto' type
Don't use 'auto' as type, unless for complex iterators or very complex
types.
### don't use trailing whitespaces
don't.
### no missing \newline at the end of file
make sure each file has a final \n newline.
### c++ keyword indentation:
The keyword 'public', 'protected', 'private' should be intended 1 character
less than the methods.
Example:
```cpp
private:
int field_;
```
instead of:
```cpp
private:
int field_;
```
### vertical space
keep the code compact vertically. That includes shader code, too.
Use only one statement per line.
### finally
Make sure everything is reflected in clang-format.
## Development Protocols
### Adding a New Visual Effect
1. **Implement**: Create or update a class in `src/gpu/demo_effects.cc` (and declare in `demo_effects.h`) that inherits from `Effect`.
- Implement `init()` for one-time resource setup (e.g., using the asset system).
- Implement `compute()` if you need GPU-side physics or state updates.
- Implement `render()` to record WebGPU draw commands.
2. **Register**: Add an `EFFECT` entry to `assets/demo.seq` specifying the class name, start/end times, and any constructor arguments.
3. **Verify**: Build with `DEMO_ALL_OPTIONS=ON` and use `--seek` to test your effect at its specific timestamp.
|
