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
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
|
# The Node file format
GSK render nodes can be serialized and deserialized using APIs such as `gsk_render_node_serialize()` and `gsk_render_node_deserialize()`. The intended use for this is development - primarily the development of GTK - by allowing things such as creating testsuites and benchmarks, exchanging nodes in bug reports. GTK includes the `gtk4-node-editor` application for creating such test files.
The format is a text format that follows the [CSS syntax rules](https://drafts.csswg.org/css-syntax-3/). In particular, this means that every array of bytes will produce a render node when parsed, as there is a defined error recovery method. For more details on error handling, please refer to the documentation of the parsing APIs.
The grammar of a node text representation using [the CSS value definition syntax](https://drafts.csswg.org/css-values-3/#value-defs) looks like this:
**document**: `<node>\*`
**node**: container [ "name" ] { <document> } | `<node-type> [ "name" ] { <property>* }` | "name"
**property**: `<property-name>: <node> | <value> ;`
Each node has its own `<node-type>` and supports a custom set of properties, each with their own `<property-name>` and syntax. The following paragraphs document each of the nodes and their properties.
When serializing and the value of a property equals the default value, this value will not be serialized. Serialization aims to produce an output as small as possible.
To embed newlines in strings, use \A. To break a long string into multiple lines, escape the newline with a \.
# Names
### Nodes
Nodes can be given a name by adding a string after the `<node-type>` in their definition. That same node can then be used further down in the document by specifying just the name identifying the node.
### Textures
Just like nodes, textures can be referenced by name. When defining a named texture, the name has to be placed in front of the URL.
# Nodes
### container
The **container** node is a special node that allows specifying a list of child nodes. Its contents follow the same rules as an empty document.
### blend
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| bottom | `<node>` | color { } | always |
| mode | `<blend-mode>` | normal | non-default |
| top | `<node>` | color { } | always |
Creates a node like `gsk_blend_node_new()` with the given properties.
### blur
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| blur | `<number>` | 1 | non-default |
| child | `<node>` | color { } | always |
Creates a node like `gsk_blur_node_new()` with the given properties.
### border
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| colors | `<color>{1,4}` | black | non-default |
| outline | `<rounded-rect>` | 50 | always |
| widths | `<number>{1,4}` | 1 | non-default |
Creates a node like `gsk_border_node_new()` with the given properties.
For the color and width properties, the values follow the typical CSS order
of top, right, bottom, left. If the last/left value isn't given, the 2nd/right
value is used. If the 3rd/bottom value isn't given, the 1st/top value is used.
And if the 2nd/right value also isn't given, the 1st/top value is used for
every 4 values.
### cairo
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| bounds | `<rect>` | none | always |
| pixels | `<url>` | none | non-default |
| script | `<url>` | none | non-default |
The pixels are a base64-encoded data url of png data. The script is
a base64-encoded data url of a cairo script.
### clip
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| child | `<node>` | color { } | always |
| clip | `<rounded-rect>` | 50 | always |
Creates a node like `gsk_clip_node_new()` with the given properties.
As an extension, this node allows specifying a rounded rectangle for the
clip property. If that rectangle is indeed rounded, a node like
`gsk_rounded_clip_node_new()` will be created instead.
### color
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| bounds | `<rect>` | 50 | always |
| color | `<color>` | #FF00CC | always |
Creates a node like `gsk_color_node_new()` with the given properties.
The color is chosen as an error pink so it is visible while also reminding
people to change it.
### color-matrix
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| child | `<node>` | color { } | always |
| matrix | `<transform>` | none | non-default |
| offset | `<number>{4}` | 0 0 0 0 | non-default |
Creates a node like `gsk_color_matrix_node_new()` with the given properties.
The matrix property accepts a <transform> for compatibility purposes, but you
should be aware that the allowed values are meant to be used on 3D transformations,
so their naming might appear awkward. However, it is always possible to use the
matrix3d() production to specify all 16 values individually.
### conic-gradient
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| bounds | `<rect>` | 50 | always |
| center | `<point>` | 25, 25 | always |
| rotation | `<number>` | 0 | always |
| stops | `<color-stop>` | 0 #AF0, 1 #F0C | always |
Creates a node like `gsk_conic_gradient_node_new()` with the given properties.
### cross-fade
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| end | `<node>` | color { } | always |
| progress | `<number>` | 0.5 | non-default |
| start | `<node>` | color { } | always |
Creates a node like `gsk_cross_fade_node_new()` with the given properties.
### debug
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| child | `<node>` | color { } | always |
| message | `<string>` | "" | non-default |
Creates a node like `gsk_debug_node_new()` with the given properties.
### glshader
| property | syntax | default | printed |
| ---------- | ------------------ | ---------------------- | ----------- |
| bounds | `<rect>` | 50 | always |
| sourcecode | `<string>` | "" | always |
| args | `<uniform values>` | none | non-default |
| child1 | `<node>` | none | non-default |
| child2 | `<node>` | none | non-default |
| child3 | `<node>` | none | non-default |
| child4 | `<node>` | none | non-default |
Creates a GLShader node. The `sourcecode` must be a GLSL fragment shader.
The `args` must match the uniforms of simple types declared in that shader,
in order and comma-separated. The `child` properties must match the sampler
uniforms in the shader.
### inset-shadow
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| blur | `<number>` | 0 | non-default |
| color | `<color>` | black | non-default |
| dx | `<number>` | 1 | non-default |
| dy | `<number>` | 1 | non-default |
| outline | `<rounded-rect>` | 50 | always |
| spread | `<number>` | 0 | non-default |
Creates a node like `gsk_inset_shadow_node_new()` with the given properties.
### linear-gradient
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| bounds | `<rect>` | 50 | always |
| start | `<point>` | 0 0 | always |
| end | `<point>` | 0 50 | always |
| stops | `<color-stop>` | 0 #AF0, 1 #F0C | always |
Creates a node like `gsk_linear_gradient_node_new()` with the given properties.
### mask
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| source | `<node>` | color { } | always |
| mode | `<mask-mode>` | alpha | non-default |
| mask | `<node>` | color { } | always |
Creates a node like `gsk_mask_node_new()` with the given properties.
### opacity
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| child | `<node>` | color { } | always |
| opacity | `<number>` | 0.5 | non-default |
Creates a node like `gsk_transform_node_new()` with the given properties.
### outset-shadow
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| blur | `<number>` | 0 | non-default |
| color | `<color>` | black | non-default |
| dx | `<number>` | 1 | non-default |
| dy | `<number>` | 1 | non-default |
| outline | `<rounded-rect>` | 50 | always |
| spread | `<number>` | 0 | non-default |
Creates a node like `gsk_outset_shadow_node_new()` with the given properties.
### radial-gradient
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| bounds | `<rect>` | 50 | always |
| center | `<point>` | 25 25 | always |
| hradius | `<number>` | 25 | always |
| vradius | `<number>` | 25 | always |
| start | `<number>` | 0 | always |
| end | `<number>` | 1 | always |
| stops | `<color-stop>` | 0 #AF0, 1 #F0C | always |
Creates a node like `gsk_radial_gradient_node_new()` with the given properties.
### repeat
| property | syntax | default | printed |
| ----------- | ---------------- | ---------------------- | ----------- |
| bounds | `<rect>` | *bounds of child node* | non-default |
| child | `<node>` | color { } | always |
| child-bounds| `<rect>` | *bounds of child node* | non-default |
Creates a node like `gsk_repeat_node_new()` with the given properties.
### repeating-linear-gradient
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| bounds | `<rect>` | 50 | always |
| start | `<point>` | 0 0 | always |
| end | `<point>` | 0 50 | always |
| stops | `<color-stop>` | 0 #AF0, 1 #F0C | always |
Creates a node like `gsk_repeating_linear_gradient_node_new()` with the given
properties.
### repeating radial-gradient
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| bounds | `<rect>` | 50 | always |
| center | `<point>` | 25 25 | always |
| hradius | `<number>` | 25 | always |
| vradius | `<number>` | 25 | always |
| start | `<number>` | 0 | always |
| end | `<number>` | 1 | always |
| stops | `<color-stop>` | 0 #AF0, 1 #F0C | always |
Creates a node like `gsk_repeating_radial_gradient_node_new()` with the given
properties.
### rounded-clip
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| child | `<node>` | color { } | always |
| clip | `<rounded-rect>` | 50 | always |
Creates a node like `gsk_rounded_clip_node_new()` with the given properties.
### shadow
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| child | `<node>` | color { } | always |
| shadows | `<shadow>` | black 1 1 | always |
Creates a node like `gsk_shadow_node_new()` with the given properties.
### text
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| color | `<color>` | black | non-default |
| font | `<string>` | "Cantarell 11" | always |
| glyphs | `<glyphs>` | "Hello" | always |
| offset | `<point>` | 0 0 | non-default |
Creates a node like `gsk_text_node_new()` with the given properties.
If the given font does not exist or the given glyphs are invalid for the given
font, an error node will be returned.
### texture
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| bounds | `<rect>` | 50 | always |
| texture | `<url>` | *see below* | always |
Creates a node like `gsk_texture_node_new()` with the given properties.
The default texture is a 10x10 checkerboard with the top left and bottom right
5x5 being in the color #FF00CC and the other part being transparent. A possible
representation for this texture is `url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAABmJLR0QA/wD/AP+gvaeTAAAAKUlEQVQYlWP8z3DmPwMaYGQwYUQXY0IXwAUGUCGGoxkYGBiweXAoeAYAz44F3e3U1xUAAAAASUVORK5CYII=")
`.
### texture-scale
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| bounds | `<rect>` | 50 | always |
| texture | `<url>` | *see below* | always |
| filter | `filter` | *see below* | non-default |
Creates a node like `gsk_texture_scale_node_new()` with the given properties.
The default texture is a 10x10 checkerboard, just like for texture.
The possible filter values are `linear`, `nearest` and `trilinear`, with
`linear` being the default.
### transform
| property | syntax | default | printed |
| -------- | ---------------- | ---------------------- | ----------- |
| child | `<node>` | color { } | always |
| transform| `<transform>` | none | non-default |
Creates a node like `gsk_transform_node_new()` with the given properties.
|
