summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/bgfx/docs/tools.rst
blob: 9dc667a872a09fde2809d9b73fc894524d28d0c1 (plain) (blame)
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
Tools
=====

Geometry Compiler (geometryc)
-----------------------------

Converts Wavefront .obj, or glTF 2.0 mesh files to a format which is optimized for use with bgfx.

Usage::

    geometryc -f <in> -o <out>

Supported input file formats:

  ====== ============================
  Format Description
  ====== ============================
  .obj   Wavefront
  .gltf  glTF 2.0
  .glb   glTF 2.0
  ====== ============================

Options:

  -h, --help               Display this help and exit.
  -v, --version            Output version information and exit.
  -f <file path>           Input's file path.
  -o <file path>           Output's file path.
  -s, --scale <num>        Scale factor.

      --ccw                Front face is counter-clockwise winding order.

      --flipv              Flip texture coordinate V.

      --obb <num>          | Number of steps for calculating oriented bounding box.
                           | Defaults to 17.
                           | Less steps = less precise OBB.
                           | More steps = slower calculation.

      --packnormal <num>   | Normal packing.
                           | 0 - unpacked 12 bytes. (default)
                           | 1 - packed 4 bytes.

      --packuv <num>       | Texture coordinate packing.
                           | 0 - unpacked 8 bytes. (default)
                           | 1 - packed 4 bytes.

      --tangent            Calculate tangent vectors. (packing mode is the same as normal)

      --barycentric        Adds barycentric vertex attribute. (Packed in bgfx::Attrib::Color1)

  -c, --compress           Compress indices.

      --[l/r]h-up+[y/z]    Coordinate system. Defaults to '--lh-up+y' — Left-Handed +Y is up.

Geometry Viewer (geometryv)
---------------------------

A geometry viewer.

Shader Compiler (shaderc)
-------------------------

Shader Compiler is used to compile bgfx's cross-platform shader language, which based on GLSL.
It uses an ANSI C pre-processor to transform the GLSL-like language into HLSL.
This method has certain drawbacks,
but overall it's simple and allows for quick authoring of cross-platform shaders.

Some differences between bgfx's shaderc flavor of GLSL and vanilla GLSL:

-  ``bool/int`` uniforms are not allowed; all uniforms must be ``float``.
-  Attributes and varyings can only be accessed from ``main()``.
-  ``SAMPLER2D/3D/CUBE/etc.`` macros replace the ``sampler2D/3D/Cube/etc.`` tokens.
-  ``vec2/3/4_splat(<value>)`` replaces the ``vec2/3/4(<value>)`` constructor.
   ``vec2/3/4`` constructors with multiple values are still valid.
-  ``mtxFromCols/mtxFromRows`` must be used for constructing matrices.
- ``mul(x, y)`` must be used when multiplying vectors with matrices.
-  A ``varying.def.sc`` file must be used to define input/output semantics and types,
   instead of using ``attribute/in`` and ``varying/in/out``.
   This file cannot include comments, and typically only one is necessary.
-  ``$input/$output`` tokens corresponding to inputs and outputs defined in
   ``varying.def.sc`` must be used at the beginning of shader.

Defines
~~~~~~~

Shader Compiler also has the following default defines (default value is set to 0):

  =============================== ======================= ========================================
  Define symbol                   Description             Option
  =============================== ======================= ========================================
  ``BX_PLATFORM_ANDROID``         Android platform        ``--platform android``
  ``BX_PLATFORM_EMSCRIPTEN``      Emscripten platform     ``--platform asm.js``
  ``BX_PLATFORM_IOS``             iOS platform            ``--platform ios``
  ``BX_PLATFORM_LINUX``           Linux platform          ``--platform linux``
  ``BX_PLATFORM_OSX``             macOS platform          ``--platform osx``
  ``BX_PLATFORM_PS4``             PlayStation 4 platform  ``--platform orbis``
  ``BX_PLATFORM_WINDOWS``         Windows platform        ``--platform windows``
  ``BX_PLATFORM_XBOXONE``         *Not implemented*
  ------------------------------- ----------------------- ----------------------------------------
  ``BGFX_SHADER_LANGUAGE_GLSL``   GLSL profile            ``-p NNN`` and ``-p NNN_es``
  ``BGFX_SHADER_LANGUAGE_HLSL``   HLSL profile            ``-p s_N_N``
  ``BGFX_SHADER_LANGUAGE_METAL``  Metal profile           ``-p metal``
  ``BGFX_SHADER_LANGUAGE_PSSL``   PSSL profile            ``-p pssl``
  ``BGFX_SHADER_LANGUAGE_SPIRV``  SPIR-V profile          ``-p spirv`` and ``-p spirvNN-NN``
  ------------------------------- ----------------------- ----------------------------------------
  ``BGFX_SHADER_TYPE_COMPUTE``    Compute shader          ``--type compute`` or ``--type c``
  ``BGFX_SHADER_TYPE_FRAGMENT``   Fragment shader         ``--type fragment`` or ``--type f``
  ``BGFX_SHADER_TYPE_VERTEX``     Vertex shader           ``--type vertex`` or ``--type v``
  =============================== ======================= ========================================

Predefined Uniforms
~~~~~~~~~~~~~~~~~~~

  ======= =================== ====================================================================
  Type    Name                Description
  ======= =================== ====================================================================
  vec4    u_viewRect          | View rectangle.
                              | ``u_viewRect.xy`` - xy offset in screen space.
                              | ``u_viewRect.zw`` - width/height size in screen space.
  vec4    u_viewTexel         | Screen-to-texel space conversion.
                              | ``u_viewTexel.xy = 1.0/u_viewRect.zw;``
  mat4    u_view              Transform world-to-view  space.
  mat4    u_invView           Transform view-to-world  space.
  mat4    u_proj              Transform view-to-clip   space.
  mat4    u_invProj           Transform clip-to-view   space.
  mat4    u_viewProj          Transform world-to-clip  space.
  mat4    u_invViewProj       Transform clip-to-world  space.
  mat4[N] u_model             Transform local-to-world space array.
  mat4    u_modelView         Transform local-to-view  space.
  mat4    u_modelViewProj     Transform local-to-clip  space.
  float   u_alphaRef          | The reference value to which incoming alpha
                              | values are compared.
  ======= =================== ====================================================================

For more info, see the `shader helper macros
<https://github.com/bkaradzic/bgfx/blob/master/src/bgfx_shader.sh>`__.

Options:

  -h, --help                Display this help and exit.
  -v, --version             Output version information and exit.
  -f <file path>            Input's file path.
  -i <include path>         Include path. (for multiple paths use -i multiple times)
  -o <file path>            Output's file path.
  --bin2c <array name>      Generate C header file. If array name is not specified base file name will be used as name.
  --depends                 Generate makefile style depends file.
  --platform <platform>     Target platform.
  -p, --profile <profile>   Shader model.
                            Defaults to GLSL.
  --preprocess              Only pre-process.
  --define <defines>        Add defines to preprocessor. (semicolon separated)
  --raw                     Do not process shader. No preprocessor, and no glsl-optimizer. (GLSL only)
  --type <type>             Shader type.
                            Can be 'vertex', 'fragment, or 'compute'.
  --varyingdef <file path>  A varying.def.sc's file path.
  --verbose                 Be verbose.

(DX9 and DX11 only):

  --debug                   Debug information.
  --disasm                  Disassemble a compiled shader.
  -O <level>                Set optimization level.
                            Can be 0–3.
  --Werror                  Treat warnings as errors.

Building shaders
~~~~~~~~~~~~~~~~

Shaders can be compiled for all renderers by using the ``shaderc`` tool.
A Makefile to simplify building shaders is provided in the `bgfx examples
<https://github.com/bkaradzic/bgfx/tree/master/examples>`__.
D3D shaders can be only compiled on Windows.

Texture Compiler (texturec)
---------------------------

Convert PNG, TGA, DDS, KTX, and PVR textures into bgfx-supported texture formats.

Usage::

  texturec -f <in> -o <out> [-t <texture format>]

Supported file formats:

  ====== ================ ============================
  Format In/Out           Description
  ====== ================ ============================
  .bmp   (input)          Windows Bitmap.
  .dds   (input, output)  Direct Draw Surface.
  .exr   (input, output)  OpenEXR.
  .gif   (input)          Graphics Interchange Format.
  .jpg   (input)          JPEG Interchange Format.
  .hdr   (input, output)  Radiance RGBE.
  .ktx   (input, output)  Khronos Texture.
  .png   (input, output)  Portable Network Graphics.
  .psd   (input)          Photoshop Document.
  .pvr   (input)          PowerVR.
  .tga   (input)          Truevision TGA.
  ====== ================ ============================

Options:

Options:
  -h, --help               Help.
  -v, --version            Version information only.
  -f <file path>           Input file path.
  -o <file path>           Output file path.
  -t <format>              Output format type (BC1/2/3/4/5, ETC1, PVR14, etc.).
  -q <quality>             Encoding quality (default, fastest, highest).
  -m, --mips               Generate mip-maps.
      --mipskip <N>        Skip <N> number of mips.
  -n, --normalmap          Input texture is normal map. (Implies --linear)

      --equirect           Input texture is equirectangular projection of cubemap.

      --strip              Input texture is horizontal or vertical strip of cubemap.

      --sdf                Compute SDF texture.

      --ref <alpha>        Alpha reference value.

      --iqa                Image Quality Assessment

      --pma                Premultiply alpha into RGB channel.

      --linear             Input and output texture is linear color space (gamma correction won't be applied).

      --max <max size>     Maximum width/height (image will be scaled down and
                           aspect ratio will be preserved)

      --radiance <model>   Radiance cubemap filter. (Lighting model: Phong, PhongBrdf, Blinn, BlinnBrdf, GGX)

      --as <extension>     Save as.

      --formats            List all supported formats.

      --validate           **DEBUG** Validate that output image produced matches after loading.

Texture Viewer (texturev)
-------------------------

A texture viewer.