diff options
Diffstat (limited to '3rdparty/bgfx/docs/tools.rst')
-rw-r--r-- | 3rdparty/bgfx/docs/tools.rst | 243 |
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. |