Clarified docs about requirement to use command line tool to compile …

…shaders.
bkaradzic · Nov 23, 2023 · 1a32959 · 1a32959
1 parent bd0cd50
commit 1a32959
Show file tree

Hide file tree

Showing 8 changed files with 34 additions and 13 deletions.
diff --git a/bindings/bf/bgfx.bf b/bindings/bf/bgfx.bf
@@ -3005,6 +3005,8 @@ public static class bgfx
 
 	/// <summary>
 	/// Create shader from memory buffer.
+	/// @remarks
+	///   Shader binary is obtained by compiling shader offline with shaderc command line tool.
 	/// </summary>
 	///
 	/// <param name="_mem">Shader binary.</param>

diff --git a/bindings/cs/bgfx.cs b/bindings/cs/bgfx.cs
@@ -2959,6 +2959,8 @@ public struct VertexLayoutHandle {
 
 	/// <summary>
 	/// Create shader from memory buffer.
+	/// @remarks
+	///   Shader binary is obtained by compiling shader offline with shaderc command line tool.
 	/// </summary>
 	///
 	/// <param name="_mem">Shader binary.</param>

diff --git 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
@@ -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.
 /// <param name="_mem">Shader binary.</param>
 pub inline fn createShader(_mem: [*c]const Memory) ShaderHandle {
     return bgfx_create_shader(_mem);

diff --git 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
@@ -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
@@ -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
@@ -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.