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.

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 <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.

(Vulkan, DirectX and Metal):

--debug

Debug information.

(DirectX only):

--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. 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.