summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/bgfx/docs/tools.rst
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/bgfx/docs/tools.rst')
-rw-r--r--3rdparty/bgfx/docs/tools.rst243
1 files changed, 243 insertions, 0 deletions
diff --git a/3rdparty/bgfx/docs/tools.rst b/3rdparty/bgfx/docs/tools.rst
new file mode 100644
index 00000000000..9dc667a872a
--- /dev/null
+++ b/3rdparty/bgfx/docs/tools.rst
@@ -0,0 +1,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.