1# VkScript
2
3The VkScript format is a clone of the format used by VkRunner as described in
4[1].
5
6# General
7## Comments
8The # symbol can be used to start a comment which extends to the end of the
9line.
10
11## Continuations
12The \ can be used at the end of a line to signal a continuation, the
13new line will be skipped and parsing will treat the following line as a
14continuation of the current line.
15
16## Descriptor Sets and Bindings
17Any command below which accepts a binding will accept either a single integer
18value which will have a descriptor set of 0 and a binding of the value give or
19a string can be provided of the form _set integer_:_binding integer_ in which
20case the descriptor set value will be `set` and the binding value will be
21`binding`.
22
23# Sections
24
25The format is broken down into five main sections:
26 * `require`
27 * `shaders`
28 * `indices`
29 * `vertex data`
30 * `test`
31
32## Require
33The `require` section lists all of the requirements for the testing environment.
34There are four types of information that can be encoded in the require section.
35
36The _feature_ list contains a list of features that are required in
37order for the test to execute. If a feature is missing an error will be reported
38and the test will fail. The _features_ are listed below in the
39*Available Require Features* section.
40
41The _framebuffer_ and _depthstencil_ commands allow setting the format for the
42given buffer. The valid values are listed below in the *Image Formats*
43section.
44
45The _fbsize_ command allows setting the width and height of the framebuffer.
46
47The _fence\_timeout_ option allows setting an integer number of milliseconds
48for any fence timeouts.
49
50The last option is _extensions_. Any string which isn't listed above is assumed
51to be an _extension_. The extensions must be of the format [a-zA-Z0-9_]+. If the
52device extension is not available we will report it is not available and the
53test will continue.
54
55
56#### Require Examples
57
58```
59[require]
60independentBlend
61VK_KHR_storage_buffer_storage_class
62```
63
64## Shaders
65The shader section allows you to specify the content of the shaders under test.
66This can be done as GLSL, SPIRV-ASM or SPIRV-Hex depending on how the shader is
67formatted. There is also a special *passthrough* vertex shader which can be
68used which just passes the vec4 input location 0 through to the `gl_Position`.
69The shader format is specified in the header after the word `shader`. The
70default is `GLSL`, SPIRV-ASM is specified as `spirv` and SPIRV-Hex as
71`spirv hex`.
72
73The shaders accepted are:
74 * `compute`
75 * `fragment`
76 * `geometry`
77 * `tessellation control`
78 * `tessellation evaulation`
79 * `vertex`
80
81#### Shader examples
82
83```
84[fragment shader]
85#version 430
86
87layout(location = 0) out vec4 color_out;
88
89void main() {
90  color_out = vec4(1, 2, 3, 4);
91}
92
93```
94
95Other example shader header lines are:
96 * `[fragment shader spirv hex]` -- a hex encoded SPIRV binary fragment shader
97 * `[tessellation evaluation shader spirv]` -- a spirv-asm tessellation evaluation shader
98 * `[vertex shader passthrough]`
99
100## Vertex Data
101The `vertex data` section provides vertex attributes and data for `draw array`
102commands. The data is formated with a header row followed by data rows.
103
104The headers can be provided in one of two forms. The first,
105`attribute_location/format` where `attribute_location` is the location of the
106attribute to be bound. The format is one of the *Image Formats* listed below.
107The second, `attribute_location/gl_type/glsl_type`. The `gl_type` is one of
108the types listed in the *GL Types* section below. The `glsl_type` is one listed
109in the *GLSL Types* section below.
110
111#### Vertex Data example
112
113```
114[vertex data]
1150/R32G32B32_SFLOAT  1/R8G8B8_UNORM
116-1    -1 0.25       255 0 0  # ending comment
117# Another Row
1180.25  -1 0.25       255 0 255
119```
120
121## Indices
122The `indices` section contains the list of indices to use along with the
123provided `vertex data`. The `indices` are used if the `indexed` option is
124provided to the `draw arrays` command. The indices themselves are a list of
125integer indexes to use.
126
127#### Indices Example
128
129```
130[indices]
131# comment line
1321 2 3   4 5 6
133# another comment
1347 8 9  10 11 12
135```
136
137## Test
138The test section contains a list of commands which can be executed to perform
139the actual testing. The commands range from setting up pipeline parameters,
140executing compute shaders and probing buffers to verify results.
141
142
143### Draw Rect
144 * `draw rect [ortho] [patch] _x_ _y_ _width_ _height_`
145
146The `draw rect` command draws a rectangle at the given coordinates. The vertices
147are uploaded at location 0 as a `vec3`. The `ortho` modifier scales the
148coordinates to be in the range of [-1,1] instead of [0,window size]. The `patch`
149modifier sets the draw call to use a given topology. Accepted possible
150topology value are listed in *Topologies*. The patch size will be set to 4.
151
152
153### Draw Arrays
154 * `draw arrays [indexed] [instanced] _topology_ _first_vertex_ _vertex_count_ [instance_count]`
155
156The `draw arrays` command uses data from the `vertex data` section when executing
157the draw command. The `topology` is from the *Topologies* list. If the `indexed`
158modifier is provided then the `indices` section data will be used as well.
159
160
161### Compute
162 * `compute _x_ _y_ _z_`
163
164Executes the compute shader with the given `x`, `y`, and `z` parameters.
165
166
167### Shader Entry Point
168 * `_stage_ entrypoint _name_`
169
170Sets the `stage` shader to use the entry point of `name` for subsequent
171executions.
172
173
174### Probe all
175 * `probe all (rgb|rgba) _r_ _g_ _b_ [_a_]`
176
177Probes the entire window to verify all pixels are of color r,g,b and optionally
178a. If `rgba` is specified then the `a` parameter is required. If `rgb` is
179specified then the `a` parameter is dis-allowed.
180
181
182### Probe
183 * `[relative] probe [rect] (rgb|rgba) (_x_, _y_[, _width_, _height_]) (_r_, _g_, _b_[, _a_])`
184
185Probes a portion of the window to verify the pixes are of color r,g,b and
186optionally a. If `rgba` is specifed then the `a` parameter is required. If
187`rgb` is specified then the `a` parameter is dis-allowed. If `rect` is specified
188then `width` and `height` are required. If `rect` is not specified then `width`
189and `height` are dis-allowed and a value of 1 will be used for each parameter.
190If the `relative` parameter is provided the coordinates are normalized to
191be in the range [0.0, 1.0].
192
193
194### Probe SSBO
195* `probe ssbo _type_ _binding_ _offset_ _comparison_ _values_+`
196
197Probes the value in the storage buffer at `binding` and `offset` within that
198binding. The `type` is the data type to be probed as seen in the *Data Types*
199section below.
200
201The comparison operators are:
202 * `==`   (equal)
203 * `!=`   (not equal)
204 * `<`    (less than)
205 * '>'    (greater than)
206 * `<=`   (less or equal)
207 * `>=`   (greater or equal)
208 * `~=`   (fuzzy equal, for floating point comparisons using `tolerances`)
209
210The `values` provided must be a non-zero multiple of the `type`.
211
212
213### Uniform
214 * `uniform _type_ _offset _values_+`
215
216Sets the push constants at `offset`. The `type` is from the *Data Types*
217section below. The `values` must be a non-zero multiple of the requested
218`type`.
219
220When setting push constant data each call to `uniform` must use the same
221`type` or the script will be rejected as invalid.
222
223
224### Unifom UBO
225 * `uniform ubo _binding_ _type_ _offset_ _values_+`
226
227Sets the values in the uniform buffer at `binding` and `offset`. The `type`
228is from the *Data Types* section below. The `values` must be a non-zero
229multiple of the requested `type`.
230
231When setting data into a single `binding`, each call to `uniform ubo` must
232use the same `type` or the script will be rejected as invalid.
233
234
235### SSBO size
236 * `ssbo _binding_ _size_`
237
238Sets the number of elements in the SSBO at `binding` to `size`. The buffer will
239be created with a default format of `char`. This default format will be
240overridden by a call to `ssbo subdata` or `probe ssbo`.
241
242
243### SSBO subdata
244 * `ssbo _binding_ subdata _type_ _offset_ _values_+`
245
246Sets the value of the buffer at `binding` and `offset`. The `type` is from the
247*Data Types* section below. The `values` must be a non-zero multiple of the
248requested `type`. The offset must be a multiple of the _type_ size in bytes.
249
250When setting data into a single `binding`, each call to `ssbo subdata` must
251use the same `type` or the script will be rejected as invalid.
252
253
254### Patch Parameters
255 * `patch parameter vertices _count_`
256
257Sets the number of control points for tessellation patches to `count`. Defaults
258to 3.
259
260
261### Tolerance
262 * `tolerance tolerance0 [tolerance1 tolerance2 tolerance3]`
263
264The `tolerance` command sets the amount of fuzzyness used when using the `~=`
265comparator. If a single tolerance value is set it is used for every comparison.
266If all four values are set then each `vecN` command will use the first `N`
267tolerance values. Each column of a `matMxN` will also use the first `N`
268tolerances. A tolerance maybe either a number or a percentage `0.01%`.
269
270
271### Clear Color
272 * `clear color _r_ _g_ _b_ _a_`
273
274Sets the clear color. Defaults to (0, 0, 0, 0).
275
276
277### Clear Depth
278 * `clear depth _value_`
279
280Sets the depth clear value. The _value_ is a float and defaults to 1.0.
281
282
283### Clear Stencil
284 * `clear stencil _value_`
285
286Sets the stencil clear value. The _value_ is an integer and defaults to 0.
287
288
289### Clear
290 * `clear`
291
292Clears the framebuffer.
293
294### Pipeline Configuration
295There are a number of pipeline flags which can be set to alter execution. Each
296draw call uses the pipeline configuration that was specified prior to the draw
297call.
298
299The pipeline commands with their accepted data are:
300 * `primitiveRestartEnable <bool>`
301 * `depthClampEnable <bool>`
302 * `rasterizerDiscardEnable <bool>`
303 * `depthBiasEnable <bool>`
304 * `logicOpEnable <bool>`
305 * `blendEnable <bool>`
306 * `depthTestEnable <bool>`
307 * `depthWriteEnable <bool>`
308 * `depthBoundsTestEnable <bool>`
309 * `stencilTestEnable <bool>`
310 * `topology <VkPrimitiveTopology>`
311 * `polygonMode <VkPolygonMode>`
312 * `logicOp <VkLogicOp>`
313 * `frontFace <VkFrontFace>`
314 * `cullMode <VkCullMode>`
315 * `depthBiasConstantFactor <float>`
316 * `depthBiasClamp <float>`
317 * `depthBiasSlopeFactor <float>`
318 * `lineWidth <float>`
319 * `minDepthBounds <float>`
320 * `maxDepthBounds <float>`
321 * `srcColorBlendFactor <VkBlendFactor>`
322 * `dstColorBlendFactor <VkBlendFactor>`
323 * `srcAlphaBlendFactor <VkBlendFactor>`
324 * `dstAlphaBlendFactor <VkBlendFactor>`
325 * `colorBlendOp <VkBlendOp>`
326 * `alphaBlendOp <VkBlendOp>`
327 * `depthCompareOp <VkCompareOp>`
328 * `front.compareOp <VkCompareOp>`
329 * `back.compareOp <VkCompareOp>`
330 * `front.failOp <VkStencilOp>`
331 * `front.passOp <VkStencilOp>`
332 * `front.depthFailOp <VkStencilOp>`
333 * `back.failOp <VkStencilOp>`
334 * `back.passOp <VkStencilOp>`
335 * `back.depthFailOp <VkStencilOp>`
336 * `front.reference <uint32_t>`
337 * `back.reference <uint32_t>`
338 * `colorWriteMask <VkColorComponent bitmask>`
339
340#### Test Example
341
342```
343[test]
344clear color 1 0.4 0.5 0.2
345clear
346relative probe rect rgba (0.0, 0.0, 1.0, 1.0) (1.0, 0.4, 0.5, 0.2)
347```
348
349### Data Types
350 * `int`
351 * `uint`
352 * `int8_t`
353 * `uint8_t`
354 * `int16_t`
355 * `uint16_t`
356 * `int64_t`
357 * `uint64_t`
358 * `float`
359 * `double`
360 * `vec`
361 * `vec[234]`
362 * `dvec`
363 * `dvec[234]`
364 * `ivec`
365 * `ivec[234]`
366 * `uvec`
367 * `uvec[234]`
368 * `i8vec`
369 * `i8vec[234]`
370 * `u8vec`
371 * `u8vec[234]`
372 * `i16vec`
373 * `i16vec[234]`
374 * `u16vec`
375 * `u16vec[234]`
376 * `i64vec`
377 * `i64vec[234]`
378 * `u64vec`
379 * `u64vec[234]`
380 * `mat`
381 * `mat[234]x[234]`
382 * `dmat`
383 * `dmat[234]x[234]`
384
385### Topologies
386 * `PATCH_LIST`
387 * `POINT_LIST`
388 * `GL_LINE_STRIP_ADJACENCY`
389 * `GL_LINE_STRIP`
390 * `GL_LINES`
391 * `GL_LINES_ADJACENCY`
392 * `GL_PATCHES`
393 * `GL_POINTS`
394 * `GL_TRIANGLE_STRIP`
395 * `GL_TRIANGLE_FAN`
396 * `GL_TRIANGLES`
397 * `GL_TRIANGLES_ADJACENCY`
398 * `GL_TRIANGLE_STRIP_ADJACENCY`
399 * `LINE_LIST`
400 * `LINE_LIST_WITH_ADJACENCY`
401 * `LINE_STRIP`
402 * `LINE_STRIP_WITH_ADJACENCY`
403 * `TRIANGLE_FAN`
404 * `TRIANGLE_LIST`
405 * `TRIANGLE_LIST_WITH_ADJACENCY`
406 * `TRIANGLE_STRIP`
407 * `TRIANGLE_STRIP_WITH_ADJACENCY`
408
409
410### GL Types
411 * `byte`
412 * `ubyte`
413 * `short`
414 * `ushort`
415 * `int`
416 * `uint`
417 * `half`
418 * `float`
419 * `double`
420
421### GLSL Types
422 * `int`
423 * `uint`
424 * `float`
425 * `double`
426 * `vec`
427 * `vec2`
428 * `vec3`
429 * `vec4`
430 * `dvec`
431 * `dvec2`
432 * `dvec3`
433 * `dvec4`
434 * `uvec`
435 * `uvec2`
436 * `uvec3`
437 * `uvec4`
438 * `ivec`
439 * `ivec2`
440 * `ivec3`
441 * `ivec4`
442
443### Available Require Features
444  * `robustBufferAccess`
445  * `fullDrawIndexUint32`
446  * `imageCubeArray`
447  * `independentBlend`
448  * `geometryShader`
449  * `tessellationShader`
450  * `sampleRateShading`
451  * `dualSrcBlend`
452  * `logicOp`
453  * `multiDrawIndirect`
454  * `drawIndirectFirstInstance`
455  * `depthClamp`
456  * `depthBiasClamp`
457  * `fillModeNonSolid`
458  * `depthBounds`
459  * `wideLines`
460  * `largePoints`
461  * `alphaToOne`
462  * `multiViewport`
463  * `samplerAnisotropy`
464  * `textureCompressionETC2`
465  * `textureCompressionASTC_LDR`
466  * `textureCompressionBC`
467  * `occlusionQueryPrecise`
468  * `pipelineStatisticsQuery`
469  * `vertexPipelineStoresAndAtomics`
470  * `fragmentStoresAndAtomics`
471  * `shaderTessellationAndGeometryPointSize`
472  * `shaderImageGatherExtended`
473  * `shaderStorageImageExtendedFormats`
474  * `shaderStorageImageMultisample`
475  * `shaderStorageImageReadWithoutFormat`
476  * `shaderStorageImageWriteWithoutFormat`
477  * `shaderUniformBufferArrayDynamicIndexing`
478  * `shaderSampledImageArrayDynamicIndexing`
479  * `shaderStorageBufferArrayDynamicIndexing`
480  * `shaderStorageImageArrayDynamicIndexing`
481  * `shaderClipDistance`
482  * `shaderCullDistance`
483  * `shaderFloat64`
484  * `shaderInt64`
485  * `shaderInt16`
486  * `shaderResourceResidency`
487  * `shaderResourceMinLod`
488  * `sparseBinding`
489  * `sparseResidencyBuffer`
490  * `sparseResidencyImage2D`
491  * `sparseResidencyImage3D`
492  * `sparseResidency2Samples`
493  * `sparseResidency4Samples`
494  * `sparseResidency8Samples`
495  * `sparseResidency16Samples`
496  * `sparseResidencyAliased`
497  * `variableMultisampleRate`
498  * `inheritedQueries`
499
500### Image Formats
501  * `A1R5G5B5_UNORM_PACK16`
502  * `A2B10G10R10_SINT_PACK32`
503  * `A2B10G10R10_SNORM_PACK32`
504  * `A2B10G10R10_SSCALED_PACK32`
505  * `A2B10G10R10_UINT_PACK32`
506  * `A2B10G10R10_UNORM_PACK32`
507  * `A2B10G10R10_USCALED_PACK32`
508  * `A2R10G10B10_SINT_PACK32`
509  * `A2R10G10B10_SNORM_PACK32`
510  * `A2R10G10B10_SSCALED_PACK32`
511  * `A2R10G10B10_UINT_PACK32`
512  * `A2R10G10B10_UNORM_PACK32`
513  * `A2R10G10B10_USCALED_PACK32`
514  * `A8B8G8R8_SINT_PACK32`
515  * `A8B8G8R8_SNORM_PACK32`
516  * `A8B8G8R8_SRGB_PACK32`
517  * `A8B8G8R8_SSCALED_PACK32`
518  * `A8B8G8R8_UINT_PACK32`
519  * `A8B8G8R8_UNORM_PACK32`
520  * `A8B8G8R8_USCALED_PACK32`
521  * `B10G11R11_UFLOAT_PACK32`
522  * `B4G4R4A4_UNORM_PACK16`
523  * `B5G5R5A1_UNORM_PACK16`
524  * `B5G6R5_UNORM_PACK16`
525  * `B8G8R8A8_SINT`
526  * `B8G8R8A8_SNORM`
527  * `B8G8R8A8_SRGB`
528  * `B8G8R8A8_SSCALED`
529  * `B8G8R8A8_UINT`
530  * `B8G8R8A8_UNORM`
531  * `B8G8R8A8_USCALED`
532  * `B8G8R8_SINT`
533  * `B8G8R8_SNORM`
534  * `B8G8R8_SRGB`
535  * `B8G8R8_SSCALED`
536  * `B8G8R8_UINT`
537  * `B8G8R8_UNORM`
538  * `B8G8R8_USCALED`
539  * `D16_UNORM`
540  * `D16_UNORM_S8_UINT`
541  * `D24_UNORM_S8_UINT`
542  * `D32_SFLOAT`
543  * `D32_SFLOAT_S8_UINT`
544  * `R16G16B16A16_SFLOAT`
545  * `R16G16B16A16_SINT`
546  * `R16G16B16A16_SNORM`
547  * `R16G16B16A16_SSCALED`
548  * `R16G16B16A16_UINT`
549  * `R16G16B16A16_UNORM`
550  * `R16G16B16A16_USCALED`
551  * `R16G16B16_SFLOAT`
552  * `R16G16B16_SINT`
553  * `R16G16B16_SNORM`
554  * `R16G16B16_SSCALED`
555  * `R16G16B16_UINT`
556  * `R16G16B16_UNORM`
557  * `R16G16B16_USCALED`
558  * `R16G16_SFLOAT`
559  * `R16G16_SINT`
560  * `R16G16_SNORM`
561  * `R16G16_SSCALED`
562  * `R16G16_UINT`
563  * `R16G16_UNORM`
564  * `R16G16_USCALED`
565  * `R16_SFLOAT`
566  * `R16_SINT`
567  * `R16_SNORM`
568  * `R16_SSCALED`
569  * `R16_UINT`
570  * `R16_UNORM`
571  * `R16_USCALED`
572  * `R32G32B32A32_SFLOAT`
573  * `R32G32B32A32_SINT`
574  * `R32G32B32A32_UINT`
575  * `R32G32B32_SFLOAT`
576  * `R32G32B32_SINT`
577  * `R32G32B32_UINT`
578  * `R32G32_SFLOAT`
579  * `R32G32_SINT`
580  * `R32G32_UINT`
581  * `R32_SFLOAT`
582  * `R32_SINT`
583  * `R32_UINT`
584  * `R4G4B4A4_UNORM_PACK16`
585  * `R4G4_UNORM_PACK8`
586  * `R5G5B5A1_UNORM_PACK16`
587  * `R5G6B5_UNORM_PACK16`
588  * `R64G64B64A64_SFLOAT`
589  * `R64G64B64A64_SINT`
590  * `R64G64B64A64_UINT`
591  * `R64G64B64_SFLOAT`
592  * `R64G64B64_SINT`
593  * `R64G64B64_UINT`
594  * `R64G64_SFLOAT`
595  * `R64G64_SINT`
596  * `R64G64_UINT`
597  * `R64_SFLOAT`
598  * `R64_SINT`
599  * `R64_UINT`
600  * `R8G8B8A8_SINT`
601  * `R8G8B8A8_SNORM`
602  * `R8G8B8A8_SRGB`
603  * `R8G8B8A8_SSCALED`
604  * `R8G8B8A8_UINT`
605  * `R8G8B8A8_UNORM`
606  * `R8G8B8A8_USCALED`
607  * `R8G8B8_SINT`
608  * `R8G8B8_SNORM`
609  * `R8G8B8_SRGB`
610  * `R8G8B8_SSCALED`
611  * `R8G8B8_UINT`
612  * `R8G8B8_UNORM`
613  * `R8G8B8_USCALED`
614  * `R8G8_SINT`
615  * `R8G8_SNORM`
616  * `R8G8_SRGB`
617  * `R8G8_SSCALED`
618  * `R8G8_UINT`
619  * `R8G8_UNORM`
620  * `R8G8_USCALED`
621  * `R8_SINT`
622  * `R8_SNORM`
623  * `R8_SRGB`
624  * `R8_SSCALED`
625  * `R8_UINT`
626  * `R8_UNORM`
627  * `R8_USCALED`
628  * `S8_UINT`
629  * `X8_D24_UNORM_PACK32`
630
6311- https://github.com/Igalia/vkrunner/blob/d817f8b186cccebed89471580a685dc80a330946/README.md
632