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 -o 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 Input's file path. -o Output's file path. -s, --scale Scale factor. --ccw Front face is counter-clockwise winding order. --flipv Flip texture coordinate V. --obb | Number of steps for calculating oriented bounding box. | Defaults to 17. | Less steps = less precise OBB. | More steps = slower calculation. --packnormal | Normal packing. | 0 - unpacked 12 bytes. (default) | 1 - packed 4 bytes. --packuv | 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()`` replaces the ``vec2/3/4()`` 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 `__. Vertex Shader Attributes ~~~~~~~~~~~~~~~~~~~~~~~~ ``$input`` tokens for vertex shader can be only following: ================ =================== Attribute bgfx::Attrib::Enum ================ =================== a_position Position a_normal Normal a_tangent Tangent a_bitangent Bitangent a_color0 Color0 a_color1 Color1 a_color2 Color2 a_color3 Color3 a_indices Indices a_weight Weight a_texcoord0 TexCoord0 a_texcoord1 TexCoord1 a_texcoord2 TexCoord2 a_texcoord3 TexCoord3 a_texcoord4 TexCoord4 a_texcoord5 TexCoord5 a_texcoord6 TexCoord6 a_texcoord7 TexCoord7 ================ =================== In ``varying.def.sc``, instance buffer input must use ``i_dataN`` as identifier where ``N`` is the index of the attribute in the buffer. Type must be ``vec4``, and the stride must be multiple of 16. The semantic must be ``TEXCOORDN`` with a decreasing index starting from ``TEXCOORD7``. :: vec4 i_data0 : TEXCOORD7; vec4 i_data1 : TEXCOORD6; vec4 i_data2 : TEXCOORD5; vec4 i_data3 : TEXCOORD4; vec4 i_data4 : TEXCOORD3; Options ~~~~~~~ Options: -h, --help Display this help and exit. -v, --version Output version information and exit. -f Input's file path. -i Include path. (for multiple paths use -i multiple times) -o Output's file path. --bin2c 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 Target platform. -p, --profile Shader model. Defaults to GLSL. --preprocess Only pre-process. --define Add defines to preprocessor. (semicolon separated) --raw Do not process shader. No preprocessor, and no glsl-optimizer. (GLSL only) --type Shader type. Can be 'vertex', 'fragment, or 'compute'. --varyingdef A varying.def.sc's file path. --verbose Be verbose. (Vulkan, DirectX and Metal): --debug Debug information. (DirectX only): --disasm Disassemble a compiled shader. -O 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 `__. 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 -o [-t ] 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 Input file path. -o Output file path. -t Output format type (BC1/2/3/4/5, ETC1, PVR14, etc.). -q Encoding quality (default, fastest, highest). -m, --mips Generate mip-maps. --mipskip Skip 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 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 Maximum width/height (image will be scaled down and aspect ratio will be preserved) --radiance Radiance cubemap filter. (Lighting model: Phong, PhongBrdf, Blinn, BlinnBrdf, GGX) --as Save as. --formats List all supported formats. --validate **DEBUG** Validate that output image produced matches after loading. Texture Viewer (texturev) ------------------------- A texture viewer.