From 1a329595aae77715210f326f857a055af437f280 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=91=D1=80=D0=B0=D0=BD=D0=B8=D0=BC=D0=B8=D1=80=20=D0=9A?= =?UTF-8?q?=D0=B0=D1=80=D0=B0=D1=9F=D0=B8=D1=9B?= Date: Wed, 22 Nov 2023 23:14:09 -0800 Subject: [PATCH] Clarified docs about requirement to use command line tool to compile shaders. --- bindings/bf/bgfx.bf | 2 ++ bindings/cs/bgfx.cs | 2 ++ bindings/d/package.d | 28 +++++++++++++++------------- bindings/zig/bgfx.zig | 2 ++ docs/bgfx.rst | 4 ++++ include/bgfx/bgfx.h | 3 +++ include/bgfx/c99/bgfx.h | 2 ++ scripts/bgfx.idl | 4 ++++ 8 files changed, 34 insertions(+), 13 deletions(-) diff --git a/bindings/bf/bgfx.bf b/bindings/bf/bgfx.bf index cbf3033271..6fb2ed9dc5 100644 --- a/bindings/bf/bgfx.bf +++ b/bindings/bf/bgfx.bf @@ -3005,6 +3005,8 @@ public static class bgfx /// /// Create shader from memory buffer. + /// @remarks + /// Shader binary is obtained by compiling shader offline with shaderc command line tool. /// /// /// Shader binary. diff --git a/bindings/cs/bgfx.cs b/bindings/cs/bgfx.cs index c1d07b144d..64fd470b30 100644 --- a/bindings/cs/bgfx.cs +++ b/bindings/cs/bgfx.cs @@ -2959,6 +2959,8 @@ public struct VertexLayoutHandle { /// /// Create shader from memory buffer. + /// @remarks + /// Shader binary is obtained by compiling shader offline with shaderc command line tool. /// /// /// Shader binary. diff --git a/bindings/d/package.d b/bindings/d/package.d index ef846b0d6b..180f468b99 100644 --- a/bindings/d/package.d +++ b/bindings/d/package.d @@ -1007,7 +1007,7 @@ extern(C++, "bgfx") struct Caps{ Supported functionality. @attention See `BGFX_CAPS_*` flags at https://bkaradzic.github.io/bgfx/bgfx.html#available-caps */ - uc_int64 supported; + c_uint64 supported; ushort vendorID; ///Selected GPU vendor PCI id. ushort deviceID; ///Selected GPU device id. bool homogeneousDepth; ///True when NDC depth is in [-1, 1] range, otherwise its [0, 1]. @@ -1132,7 +1132,7 @@ extern(C++, "bgfx") struct Init{ matching ID. */ ushort deviceID; - uc_int64 capabilities; ///Capabilities initialization mask (default: UINT64_MAX). + c_uint64 capabilities; ///Capabilities initialization mask (default: UINT64_MAX). bool debug_; ///Enable device for debugging. bool profile; ///Enable device for profiling. PlatformData platformData; ///Platform data. @@ -1415,7 +1415,7 @@ extern(C++, "bgfx") struct Encoder{ rgba = Sets blend factor used by `BGFX_STATE_BLEND_FACTOR` and `BGFX_STATE_BLEND_INV_FACTOR` blend modes. */ - {q{void}, q{setState}, q{uc_int64 state, uint rgba=0}, ext: `C++`}, + {q{void}, q{setState}, q{c_uint64 state, uint rgba=0}, ext: `C++`}, /** Set condition for rendering. @@ -2394,6 +2394,8 @@ mixin(joinFnBinds((){ /** * Create shader from memory buffer. + * Remarks: + * Shader binary is obtained by compiling shader offline with shaderc command line tool. Params: mem = Shader binary. */ @@ -2462,7 +2464,7 @@ mixin(joinFnBinds((){ format = Texture format. See: `TextureFormat::Enum`. flags = Texture flags. See `BGFX_TEXTURE_*`. */ - {q{bool}, q{isTextureValid}, q{ushort depth, bool cubeMap, ushort numLayers, bgfx.fakeenum.TextureFormat.Enum format, uc_int64 flags}, ext: `C++, "bgfx"`}, + {q{bool}, q{isTextureValid}, q{ushort depth, bool cubeMap, ushort numLayers, bgfx.fakeenum.TextureFormat.Enum format, c_uint64 flags}, ext: `C++, "bgfx"`}, /** * Validate frame buffer parameters. @@ -2499,7 +2501,7 @@ mixin(joinFnBinds((){ skip = Skip top level mips when parsing texture. info = When non-`NULL` is specified it returns parsed texture information. */ - {q{TextureHandle}, q{createTexture}, q{const(Memory)* mem, uc_int64 flags, ubyte skip=0, TextureInfo* info=null}, ext: `C++, "bgfx"`}, + {q{TextureHandle}, q{createTexture}, q{const(Memory)* mem, c_uint64 flags, ubyte skip=0, TextureInfo* info=null}, ext: `C++, "bgfx"`}, /** * Create 2D texture. @@ -2520,7 +2522,7 @@ mixin(joinFnBinds((){ `_mem` is NULL content of the texture is uninitialized. When `_numLayers` is more than 1, expected memory layout is texture and all mips together for each array element. */ - {q{TextureHandle}, q{createTexture2D}, q{ushort width, ushort height, bool hasMIPs, ushort numLayers, bgfx.fakeenum.TextureFormat.Enum format, uc_int64 flags, const(Memory)* mem=null}, ext: `C++, "bgfx"`}, + {q{TextureHandle}, q{createTexture2D}, q{ushort width, ushort height, bool hasMIPs, ushort numLayers, bgfx.fakeenum.TextureFormat.Enum format, c_uint64 flags, const(Memory)* mem=null}, ext: `C++, "bgfx"`}, /** * Create texture with size based on back-buffer ratio. Texture will maintain ratio @@ -2538,7 +2540,7 @@ mixin(joinFnBinds((){ - `BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]` - Point or anisotropic sampling. */ - {q{TextureHandle}, q{createTexture2D}, q{bgfx.fakeenum.BackbufferRatio.Enum ratio, bool hasMIPs, ushort numLayers, bgfx.fakeenum.TextureFormat.Enum format, uc_int64 flags=Texture.none|Sampler.none}, ext: `C++, "bgfx"`}, + {q{TextureHandle}, q{createTexture2D}, q{bgfx.fakeenum.BackbufferRatio.Enum ratio, bool hasMIPs, ushort numLayers, bgfx.fakeenum.TextureFormat.Enum format, c_uint64 flags=Texture.none|Sampler.none}, ext: `C++, "bgfx"`}, /** * Create 3D texture. @@ -2558,7 +2560,7 @@ mixin(joinFnBinds((){ `_mem` is NULL content of the texture is uninitialized. When `_numLayers` is more than 1, expected memory layout is texture and all mips together for each array element. */ - {q{TextureHandle}, q{createTexture3D}, q{ushort width, ushort height, ushort depth, bool hasMIPs, bgfx.fakeenum.TextureFormat.Enum format, uc_int64 flags=Texture.none|Sampler.none, const(Memory)* mem=null}, ext: `C++, "bgfx"`}, + {q{TextureHandle}, q{createTexture3D}, q{ushort width, ushort height, ushort depth, bool hasMIPs, bgfx.fakeenum.TextureFormat.Enum format, c_uint64 flags=Texture.none|Sampler.none, const(Memory)* mem=null}, ext: `C++, "bgfx"`}, /** * Create Cube texture. @@ -2578,7 +2580,7 @@ mixin(joinFnBinds((){ `_mem` is NULL content of the texture is uninitialized. When `_numLayers` is more than 1, expected memory layout is texture and all mips together for each array element. */ - {q{TextureHandle}, q{createTextureCube}, q{ushort size, bool hasMIPs, ushort numLayers, bgfx.fakeenum.TextureFormat.Enum format, uc_int64 flags=Texture.none|Sampler.none, const(Memory)* mem=null}, ext: `C++, "bgfx"`}, + {q{TextureHandle}, q{createTextureCube}, q{ushort size, bool hasMIPs, ushort numLayers, bgfx.fakeenum.TextureFormat.Enum format, c_uint64 flags=Texture.none|Sampler.none, const(Memory)* mem=null}, ext: `C++, "bgfx"`}, /** * Update 2D texture. @@ -2698,7 +2700,7 @@ mixin(joinFnBinds((){ - `BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]` - Point or anisotropic sampling. */ - {q{FrameBufferHandle}, q{createFrameBuffer}, q{ushort width, ushort height, bgfx.fakeenum.TextureFormat.Enum format, uc_int64 textureFlags=SamplerU.clamp|SamplerV.clamp}, ext: `C++, "bgfx"`}, + {q{FrameBufferHandle}, q{createFrameBuffer}, q{ushort width, ushort height, bgfx.fakeenum.TextureFormat.Enum format, c_uint64 textureFlags=SamplerU.clamp|SamplerV.clamp}, ext: `C++, "bgfx"`}, /** * Create frame buffer with size based on back-buffer ratio. Frame buffer will maintain ratio @@ -2714,7 +2716,7 @@ mixin(joinFnBinds((){ - `BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]` - Point or anisotropic sampling. */ - {q{FrameBufferHandle}, q{createFrameBuffer}, q{bgfx.fakeenum.BackbufferRatio.Enum ratio, bgfx.fakeenum.TextureFormat.Enum format, uc_int64 textureFlags=SamplerU.clamp|SamplerV.clamp}, ext: `C++, "bgfx"`}, + {q{FrameBufferHandle}, q{createFrameBuffer}, q{bgfx.fakeenum.BackbufferRatio.Enum ratio, bgfx.fakeenum.TextureFormat.Enum format, c_uint64 textureFlags=SamplerU.clamp|SamplerV.clamp}, ext: `C++, "bgfx"`}, /** * Create MRT frame buffer from texture handles (simple). @@ -3076,7 +3078,7 @@ mixin(joinFnBinds((){ - `BGFX_SAMPLER_[MIN/MAG/MIP]_[POINT/ANISOTROPIC]` - Point or anisotropic sampling. */ - {q{size_t}, q{overrideInternal}, q{TextureHandle handle, ushort width, ushort height, ubyte numMIPs, bgfx.fakeenum.TextureFormat.Enum format, uc_int64 flags}, ext: `C++, "bgfx"`}, + {q{size_t}, q{overrideInternal}, q{TextureHandle handle, ushort width, ushort height, ubyte numMIPs, bgfx.fakeenum.TextureFormat.Enum format, c_uint64 flags}, ext: `C++, "bgfx"`}, /** * Sets a debug marker. This allows you to group graphics calls together for easy browsing in @@ -3111,7 +3113,7 @@ mixin(joinFnBinds((){ rgba = Sets blend factor used by `BGFX_STATE_BLEND_FACTOR` and `BGFX_STATE_BLEND_INV_FACTOR` blend modes. */ - {q{void}, q{setState}, q{uc_int64 state, uint rgba=0}, ext: `C++, "bgfx"`}, + {q{void}, q{setState}, q{c_uint64 state, uint rgba=0}, ext: `C++, "bgfx"`}, /** * Set condition for rendering. diff --git a/bindings/zig/bgfx.zig b/bindings/zig/bgfx.zig index faffaa7e75..9f09d94098 100644 --- a/bindings/zig/bgfx.zig +++ b/bindings/zig/bgfx.zig @@ -2401,6 +2401,8 @@ pub inline fn destroyIndirectBuffer(_handle: IndirectBufferHandle) void { extern fn bgfx_destroy_indirect_buffer(_handle: IndirectBufferHandle) void; /// Create shader from memory buffer. +/// @remarks +/// Shader binary is obtained by compiling shader offline with shaderc command line tool. /// Shader binary. pub inline fn createShader(_mem: [*c]const Memory) ShaderHandle { return bgfx_create_shader(_mem); diff --git a/docs/bgfx.rst b/docs/bgfx.rst index e17513e3b9..6f80a742ef 100644 --- a/docs/bgfx.rst +++ b/docs/bgfx.rst @@ -481,6 +481,10 @@ Resources Shaders and Programs ~~~~~~~~~~~~~~~~~~~~ +.. note:: + + Shaders must be compiled with offline command line too shaderc. + .. doxygenfunction:: bgfx::createShader .. doxygenfunction:: bgfx::getShaderUniforms .. doxygenfunction:: bgfx::destroy(ShaderHandle _handle) diff --git a/include/bgfx/bgfx.h b/include/bgfx/bgfx.h index 8a2655c8ce..d9e4da4832 100644 --- a/include/bgfx/bgfx.h +++ b/include/bgfx/bgfx.h @@ -2617,6 +2617,9 @@ namespace bgfx /// /// @returns Shader handle. /// + /// @remarks + /// Shader binary is obtained by compiling shader offline with shaderc command line tool. + /// /// @attention C99's equivalent binding is `bgfx_create_shader`. /// ShaderHandle createShader(const Memory* _mem); diff --git a/include/bgfx/c99/bgfx.h b/include/bgfx/c99/bgfx.h index 1f303f396b..b2029dba6f 100644 --- a/include/bgfx/c99/bgfx.h +++ b/include/bgfx/c99/bgfx.h @@ -1657,6 +1657,8 @@ BGFX_C_API void bgfx_destroy_indirect_buffer(bgfx_indirect_buffer_handle_t _hand /** * Create shader from memory buffer. + * @remarks + * Shader binary is obtained by compiling shader offline with shaderc command line tool. * * @param[in] _mem Shader binary. * diff --git a/scripts/bgfx.idl b/scripts/bgfx.idl index 1a329da24e..e703547369 100644 --- a/scripts/bgfx.idl +++ b/scripts/bgfx.idl @@ -1563,6 +1563,10 @@ func.destroy { cname = "destroy_indirect_buffer" } .handle "IndirectBufferHandle" --- Indirect buffer handle. --- Create shader from memory buffer. +--- +--- @remarks +--- Shader binary is obtained by compiling shader offline with shaderc command line tool. +--- func.createShader "ShaderHandle" --- Shader handle. .mem "const Memory*" --- Shader binary.