Improved documentation. Added IDL docs. (#3619)

bindings/bf/bgfx.bf

@@ -1618,192 +1618,192 @@ public static class bgfx
 	public enum TextureFormat : uint32
 	{
 		/// <summary>
-		/// DXT1 R5G6B5A1
+		/// Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP.
 		/// </summary>
 		BC1,
 	
 		/// <summary>
-		/// DXT3 R5G6B5A4
+		/// Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP.
 		/// </summary>
 		BC2,
 	
 		/// <summary>
-		/// DXT5 R5G6B5A8
+		/// Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP.
 		/// </summary>
 		BC3,
 	
 		/// <summary>
-		/// LATC1/ATI1 R8
+		/// Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP.
 		/// </summary>
 		BC4,
 	
 		/// <summary>
-		/// LATC2/ATI2 RG8
+		/// Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP.
 		/// </summary>
 		BC5,
 	
 		/// <summary>
-		/// BC6H RGB16F
+		/// Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP.
 		/// </summary>
 		BC6H,
 	
 		/// <summary>
-		/// BC7 RGB 4-7 bits per color channel, 0-8 bits alpha
+		/// RGB 4-7 bits per color channel, 0-8 bits alpha. Block Compression 7. High-quality RGBA, 4-7 bits per color, 0-8 bits alpha. 8 BPP.
 		/// </summary>
 		BC7,
 	
 		/// <summary>
-		/// ETC1 RGB8
+		/// Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP.
 		/// </summary>
 		ETC1,
 	
 		/// <summary>
-		/// ETC2 RGB8
+		/// Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP.
 		/// </summary>
 		ETC2,
 	
 		/// <summary>
-		/// ETC2 RGBA8
+		/// Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP.
 		/// </summary>
 		ETC2A,
 	
 		/// <summary>
-		/// ETC2 RGB8A1
+		/// Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP.
 		/// </summary>
 		ETC2A1,
 	
 		/// <summary>
-		/// EAC R11 UNORM
+		/// ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP.
 		/// </summary>
 		EACR11,
 	
 		/// <summary>
-		/// EAC R11 SNORM
+		/// ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP.
 		/// </summary>
 		EACR11S,
 	
 		/// <summary>
-		/// EAC RG11 UNORM
+		/// ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP.
 		/// </summary>
 		EACRG11,
 	
 		/// <summary>
-		/// EAC RG11 SNORM
+		/// ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP.
 		/// </summary>
 		EACRG11S,
 	
 		/// <summary>
-		/// PVRTC1 RGB 2BPP
+		/// PowerVR Texture Compression v1. 3-channel RGB. 2 BPP.
 		/// </summary>
 		PTC12,
 	
 		/// <summary>
-		/// PVRTC1 RGB 4BPP
+		/// PowerVR Texture Compression v1. 3-channel RGB. 4 BPP.
 		/// </summary>
 		PTC14,
 	
 		/// <summary>
-		/// PVRTC1 RGBA 2BPP
+		/// PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP.
 		/// </summary>
 		PTC12A,
 	
 		/// <summary>
-		/// PVRTC1 RGBA 4BPP
+		/// PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP.
 		/// </summary>
 		PTC14A,
 	
 		/// <summary>
-		/// PVRTC2 RGBA 2BPP
+		/// PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP.
 		/// </summary>
 		PTC22,
 	
 		/// <summary>
-		/// PVRTC2 RGBA 4BPP
+		/// PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP.
 		/// </summary>
 		PTC24,
 	
 		/// <summary>
-		/// ATC RGB 4BPP
+		/// AMD Texture Compression. 3-channel RGB. 4 BPP.
 		/// </summary>
 		ATC,
 	
 		/// <summary>
-		/// ATCE RGBA 8 BPP explicit alpha
+		/// AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP.
 		/// </summary>
 		ATCE,
 	
 		/// <summary>
-		/// ATCI RGBA 8 BPP interpolated alpha
+		/// AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP.
 		/// </summary>
 		ATCI,
 	
 		/// <summary>
-		/// ASTC 4x4 8.0 BPP
+		/// Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP.
 		/// </summary>
 		ASTC4x4,
 	
 		/// <summary>
-		/// ASTC 5x4 6.40 BPP
+		/// Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP.
 		/// </summary>
 		ASTC5x4,
 	
 		/// <summary>
-		/// ASTC 5x5 5.12 BPP
+		/// Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP.
 		/// </summary>
 		ASTC5x5,
 	
 		/// <summary>
-		/// ASTC 6x5 4.27 BPP
+		/// Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP.
 		/// </summary>
 		ASTC6x5,
 	
 		/// <summary>
-		/// ASTC 6x6 3.56 BPP
+		/// Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP.
 		/// </summary>
 		ASTC6x6,
 	
 		/// <summary>
-		/// ASTC 8x5 3.20 BPP
+		/// Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP.
 		/// </summary>
 		ASTC8x5,
 	
 		/// <summary>
-		/// ASTC 8x6 2.67 BPP
+		/// Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP.
 		/// </summary>
 		ASTC8x6,
 	
 		/// <summary>
-		/// ASTC 8x8 2.00 BPP
+		/// Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP.
 		/// </summary>
 		ASTC8x8,
 	
 		/// <summary>
-		/// ASTC 10x5 2.56 BPP
+		/// Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP.
 		/// </summary>
 		ASTC10x5,
 	
 		/// <summary>
-		/// ASTC 10x6 2.13 BPP
+		/// Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP.
 		/// </summary>
 		ASTC10x6,
 	
 		/// <summary>
-		/// ASTC 10x8 1.60 BPP
+		/// Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP.
 		/// </summary>
 		ASTC10x8,
 	
 		/// <summary>
-		/// ASTC 10x10 1.28 BPP
+		/// Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP.
 		/// </summary>
 		ASTC10x10,
 	
 		/// <summary>
-		/// ASTC 12x10 1.07 BPP
+		/// Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP.
 		/// </summary>
 		ASTC12x10,
 	
 		/// <summary>
-		/// ASTC 12x12 0.89 BPP
+		/// Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP.
 		/// </summary>
 		ASTC12x12,
 	
@@ -1811,70 +1811,310 @@ public static class bgfx
 		/// Compressed formats above.
 		/// </summary>
 		Unknown,
+	
+		/// <summary>
+		/// 1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP.
+		/// </summary>
 		R1,
+	
+		/// <summary>
+		/// 8-bit single-channel alpha, unsigned normalized. 8 BPP.
+		/// </summary>
 		A8,
+	
+		/// <summary>
+		/// 8-bit single-channel red, unsigned normalized. 8 BPP.
+		/// </summary>
 		R8,
+	
+		/// <summary>
+		/// 8-bit single-channel red, signed integer. 8 BPP.
+		/// </summary>
 		R8I,
+	
+		/// <summary>
+		/// 8-bit single-channel red, unsigned integer. 8 BPP.
+		/// </summary>
 		R8U,
+	
+		/// <summary>
+		/// 8-bit single-channel red, signed normalized. 8 BPP.
+		/// </summary>
 		R8S,
+	
+		/// <summary>
+		/// 16-bit single-channel red, unsigned normalized. 16 BPP.
+		/// </summary>
 		R16,
+	
+		/// <summary>
+		/// 16-bit single-channel red, signed integer. 16 BPP.
+		/// </summary>
 		R16I,
+	
+		/// <summary>
+		/// 16-bit single-channel red, unsigned integer. 16 BPP.
+		/// </summary>
 		R16U,
+	
+		/// <summary>
+		/// 16-bit single-channel red, half-precision floating point. 16 BPP.
+		/// </summary>
 		R16F,
+	
+		/// <summary>
+		/// 16-bit single-channel red, signed normalized. 16 BPP.
+		/// </summary>
 		R16S,
+	
+		/// <summary>
+		/// 32-bit single-channel red, signed integer. 32 BPP.
+		/// </summary>
 		R32I,
+	
+		/// <summary>
+		/// 32-bit single-channel red, unsigned integer. 32 BPP.
+		/// </summary>
 		R32U,
+	
+		/// <summary>
+		/// 32-bit single-channel red, full-precision floating point. 32 BPP.
+		/// </summary>
 		R32F,
+	
+		/// <summary>
+		/// Two 8-bit channels (red, green), unsigned normalized. 16 BPP.
+		/// </summary>
 		RG8,
+	
+		/// <summary>
+		/// Two 8-bit channels (red, green), signed integer. 16 BPP.
+		/// </summary>
 		RG8I,
+	
+		/// <summary>
+		/// Two 8-bit channels (red, green), unsigned integer. 16 BPP.
+		/// </summary>
 		RG8U,
+	
+		/// <summary>
+		/// Two 8-bit channels (red, green), signed normalized. 16 BPP.
+		/// </summary>
 		RG8S,
+	
+		/// <summary>
+		/// Two 16-bit channels (red, green), unsigned normalized. 32 BPP.
+		/// </summary>
 		RG16,
+	
+		/// <summary>
+		/// Two 16-bit channels (red, green), signed integer. 32 BPP.
+		/// </summary>
 		RG16I,
+	
+		/// <summary>
+		/// Two 16-bit channels (red, green), unsigned integer. 32 BPP.
+		/// </summary>
 		RG16U,
+	
+		/// <summary>
+		/// Two 16-bit channels (red, green), half-precision floating point. 32 BPP.
+		/// </summary>
 		RG16F,
+	
+		/// <summary>
+		/// Two 16-bit channels (red, green), signed normalized. 32 BPP.
+		/// </summary>
 		RG16S,
+	
+		/// <summary>
+		/// Two 32-bit channels (red, green), signed integer. 64 BPP.
+		/// </summary>
 		RG32I,
+	
+		/// <summary>
+		/// Two 32-bit channels (red, green), unsigned integer. 64 BPP.
+		/// </summary>
 		RG32U,
+	
+		/// <summary>
+		/// Two 32-bit channels (red, green), full-precision floating point. 64 BPP.
+		/// </summary>
 		RG32F,
+	
+		/// <summary>
+		/// Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP.
+		/// </summary>
 		RGB8,
+	
+		/// <summary>
+		/// Three 8-bit channels (red, green, blue), signed integer. 24 BPP.
+		/// </summary>
 		RGB8I,
+	
+		/// <summary>
+		/// Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP.
+		/// </summary>
 		RGB8U,
+	
+		/// <summary>
+		/// Three 8-bit channels (red, green, blue), signed normalized. 24 BPP.
+		/// </summary>
 		RGB8S,
+	
+		/// <summary>
+		/// Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP.
+		/// </summary>
 		RGB9E5F,
+	
+		/// <summary>
+		/// Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP.
+		/// </summary>
 		BGRA8,
+	
+		/// <summary>
+		/// Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP.
+		/// </summary>
 		RGBA8,
+	
+		/// <summary>
+		/// Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP.
+		/// </summary>
 		RGBA8I,
+	
+		/// <summary>
+		/// Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP.
+		/// </summary>
 		RGBA8U,
+	
+		/// <summary>
+		/// Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP.
+		/// </summary>
 		RGBA8S,
+	
+		/// <summary>
+		/// Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP.
+		/// </summary>
 		RGBA16,
+	
+		/// <summary>
+		/// Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP.
+		/// </summary>
 		RGBA16I,
+	
+		/// <summary>
+		/// Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP.
+		/// </summary>
 		RGBA16U,
+	
+		/// <summary>
+		/// Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP.
+		/// </summary>
 		RGBA16F,
+	
+		/// <summary>
+		/// Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP.
+		/// </summary>
 		RGBA16S,
+	
+		/// <summary>
+		/// Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP.
+		/// </summary>
 		RGBA32I,
+	
+		/// <summary>
+		/// Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP.
+		/// </summary>
 		RGBA32U,
+	
+		/// <summary>
+		/// Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP.
+		/// </summary>
 		RGBA32F,
+	
+		/// <summary>
+		/// Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP.
+		/// </summary>
 		B5G6R5,
+	
+		/// <summary>
+		/// Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP.
+		/// </summary>
 		R5G6B5,
+	
+		/// <summary>
+		/// Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP.
+		/// </summary>
 		BGRA4,
+	
+		/// <summary>
+		/// Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP.
+		/// </summary>
 		RGBA4,
+	
+		/// <summary>
+		/// Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP.
+		/// </summary>
 		BGR5A1,
+	
+		/// <summary>
+		/// Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP.
+		/// </summary>
 		RGB5A1,
+	
+		/// <summary>
+		/// Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP.
+		/// </summary>
 		RGB10A2,
+	
+		/// <summary>
+		/// Packed 32-bit, 11-bit red, 11-bit green, 10-bit blue, unsigned floating point. No alpha. 32 BPP.
+		/// </summary>
 		RG11B10F,
 	
 		/// <summary>
 		/// Depth formats below.
 		/// </summary>
 		UnknownDepth,
+	
+		/// <summary>
+		/// 16-bit depth, unsigned normalized. 16 BPP.
+		/// </summary>
 		D16,
+	
+		/// <summary>
+		/// 24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP.
+		/// </summary>
 		D24,
+	
+		/// <summary>
+		/// 24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP.
+		/// </summary>
 		D24S8,
+	
+		/// <summary>
+		/// 32-bit depth, unsigned normalized. 32 BPP.
+		/// </summary>
 		D32,
+	
+		/// <summary>
+		/// 16-bit depth, floating point. 16 BPP.
+		/// </summary>
 		D16F,
+	
+		/// <summary>
+		/// 24-bit depth, floating point (stored as 32-bit). 32 BPP.
+		/// </summary>
 		D24F,
+	
+		/// <summary>
+		/// 32-bit depth, floating point. 32 BPP.
+		/// </summary>
 		D32F,
+	
+		/// <summary>
+		/// 8-bit stencil only, no depth. 8 BPP.
+		/// </summary>
 		D0S8,
 	
 		Count
@@ -2735,9 +2975,30 @@ public static class bgfx
 	public static extern void reset(uint32 _width, uint32 _height, uint32 _flags, TextureFormat _format);
 	
 	/// <summary>
-	/// Advance to next frame. When using multithreaded renderer, this call
+	/// Advance to next frame. This is the main frame-advancement call on the
-	/// just swaps internal buffers, kicks render thread, and returns. In
+	/// API thread (the thread from which `bgfx::init` was called).
-	/// singlethreaded renderer this call does frame rendering.
+	/// 
+	/// **Multithreaded renderer** (`BGFX_CONFIG_MULTITHREADED=1`, default):
+	/// This call waits for the render thread to finish processing the previous
+	/// frame, then swaps internal submit/render buffers, signals the render
+	/// thread to begin processing the new frame via `bgfx::renderFrame`, and
+	/// returns immediately. The render thread and API thread then run in
+	/// parallel: the API thread builds the next frame while the render thread
+	/// executes GPU commands for the current frame.
+	/// 
+	/// **Single-threaded renderer** (`BGFX_CONFIG_MULTITHREADED=0`, or when
+	/// `bgfx::renderFrame` and `bgfx::init` are called from the same thread):
+	/// This call swaps internal buffers and performs frame rendering inline
+	/// (internally calls `bgfx::renderFrame`), then returns.
+	/// 
+	/// @remarks
+	///   Must be called from the API thread (the thread that called
+	///   `bgfx::init`). In multithreaded mode, this call synchronizes with
+	///   `bgfx::renderFrame` running on the render thread via semaphores:
+	///   `bgfx::frame` waits for the render thread to finish, then posts a
+	///   signal that `bgfx::renderFrame` waits on to begin the next frame.
+	///   See also: `bgfx::renderFrame`.
+	/// 
 	/// </summary>
 	///
 	/// <param name="_flags">Frame flags. See: `BGFX_FRAME_*` for more info.   - `BGFX_FRAME_NONE` - No frame flag.   - `BGFX_FRAME_DEBUG_CAPTURE` - Capture frame with graphics debugger.   - `BGFX_FRAME_DISCARD` - Discard all draw calls.</param>
@@ -4454,16 +4715,43 @@ public static class bgfx
 	public static extern void request_screen_shot(FrameBufferHandle _handle, char8* _filePath);
 	
 	/// <summary>
-	/// Render frame.
+	/// Render frame. Executes the actual GPU rendering work for one frame.
 	/// 
-	/// @attention `bgfx::renderFrame` is blocking call. It waits for
+	/// In the default **multithreaded** configuration, `bgfx::renderFrame` runs
-	///   `bgfx::frame` to be called from API thread to process frame.
+	/// on the **render thread** while `bgfx::frame` runs on the **API thread**.
-	///   If timeout value is passed call will timeout and return even
+	/// Their interaction is as follows:
-	///   if `bgfx::frame` is not called.
 	/// 
-	/// @warning This call should be only used on platforms that don't
+	///   1. The render thread calls `bgfx::renderFrame`, which blocks waiting
-	///   allow creating separate rendering thread. If it is called before
+	///      for the API thread to signal that a new frame is ready.
-	///   to bgfx::init, render thread won't be created by bgfx::init call.
+	///   2. On the API thread, `bgfx::frame` finishes building the frame,
+	///      swaps internal submit/render buffers, and signals the render thread.
+	///   3. `bgfx::renderFrame` wakes up, executes pre-render commands,
+	///      submits GPU draw calls, executes post-render commands, flips the
+	///      back buffer, then signals back to the API thread that rendering
+	///      is complete.
+	///   4. The API thread's next `bgfx::frame` call waits for this completion
+	///      signal before swapping buffers again.
+	/// 
+	/// This double-buffered semaphore handshake allows the API thread and
+	/// render thread to run in parallel, overlapping CPU frame building with
+	/// GPU rendering.
+	/// 
+	/// @attention `bgfx::renderFrame` is a blocking call. It waits for
+	///   `bgfx::frame` to be called from the API thread to process the frame.
+	///   If a timeout value is passed, the call will return
+	///   `RenderFrame::Timeout` even if `bgfx::frame` has not been called.
+	///   A value of -1 (default) means wait indefinitely (up to
+	///   `BGFX_CONFIG_API_SEMAPHORE_TIMEOUT`).
+	/// 
+	/// @warning This call should only be used on platforms that don't allow
+	///   creating a separate rendering thread. If it is called before
+	///   `bgfx::init`, the internal render thread won't be created by the
+	///   `bgfx::init` call, and the user is responsible for calling
+	///   `bgfx::renderFrame` on the render thread each frame. If both
+	///   `bgfx::renderFrame` and `bgfx::init` are called from the same
+	///   thread, bgfx operates in single-threaded mode and `bgfx::frame`
+	///   will internally invoke `bgfx::renderFrame` automatically.
+	///   See also: `bgfx::frame`.
 	/// 
 	/// </summary>
 	///

bindings/c3/bgfx.c3

@@ -1021,184 +1021,304 @@ enum AttribType : uint
 
 enum TextureFormat : uint
 {
-	// DXT1 R5G6B5A1
+	// Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP.
 	BC1,
 
-	// DXT3 R5G6B5A4
+	// Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP.
 	BC2,
 
-	// DXT5 R5G6B5A8
+	// Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP.
 	BC3,
 
-	// LATC1/ATI1 R8
+	// Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP.
 	BC4,
 
-	// LATC2/ATI2 RG8
+	// Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP.
 	BC5,
 
-	// BC6H RGB16F
+	// Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP.
 	BC6H,
 
-	// BC7 RGB 4-7 bits per color channel, 0-8 bits alpha
+	// RGB 4-7 bits per color channel, 0-8 bits alpha. Block Compression 7. High-quality RGBA, 4-7 bits per color, 0-8 bits alpha. 8 BPP.
 	BC7,
 
-	// ETC1 RGB8
+	// Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP.
 	ETC1,
 
-	// ETC2 RGB8
+	// Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP.
 	ETC2,
 
-	// ETC2 RGBA8
+	// Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP.
 	ETC2A,
 
-	// ETC2 RGB8A1
+	// Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP.
 	ETC2A1,
 
-	// EAC R11 UNORM
+	// ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP.
 	EACR11,
 
-	// EAC R11 SNORM
+	// ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP.
 	EACR11S,
 
-	// EAC RG11 UNORM
+	// ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP.
 	EACRG11,
 
-	// EAC RG11 SNORM
+	// ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP.
 	EACRG11S,
 
-	// PVRTC1 RGB 2BPP
+	// PowerVR Texture Compression v1. 3-channel RGB. 2 BPP.
 	PTC12,
 
-	// PVRTC1 RGB 4BPP
+	// PowerVR Texture Compression v1. 3-channel RGB. 4 BPP.
 	PTC14,
 
-	// PVRTC1 RGBA 2BPP
+	// PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP.
 	PTC12A,
 
-	// PVRTC1 RGBA 4BPP
+	// PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP.
 	PTC14A,
 
-	// PVRTC2 RGBA 2BPP
+	// PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP.
 	PTC22,
 
-	// PVRTC2 RGBA 4BPP
+	// PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP.
 	PTC24,
 
-	// ATC RGB 4BPP
+	// AMD Texture Compression. 3-channel RGB. 4 BPP.
 	ATC,
 
-	// ATCE RGBA 8 BPP explicit alpha
+	// AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP.
 	ATCE,
 
-	// ATCI RGBA 8 BPP interpolated alpha
+	// AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP.
 	ATCI,
 
-	// ASTC 4x4 8.0 BPP
+	// Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP.
 	ASTC4X4,
 
-	// ASTC 5x4 6.40 BPP
+	// Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP.
 	ASTC5X4,
 
-	// ASTC 5x5 5.12 BPP
+	// Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP.
 	ASTC5X5,
 
-	// ASTC 6x5 4.27 BPP
+	// Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP.
 	ASTC6X5,
 
-	// ASTC 6x6 3.56 BPP
+	// Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP.
 	ASTC6X6,
 
-	// ASTC 8x5 3.20 BPP
+	// Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP.
 	ASTC8X5,
 
-	// ASTC 8x6 2.67 BPP
+	// Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP.
 	ASTC8X6,
 
-	// ASTC 8x8 2.00 BPP
+	// Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP.
 	ASTC8X8,
 
-	// ASTC 10x5 2.56 BPP
+	// Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP.
 	ASTC10X5,
 
-	// ASTC 10x6 2.13 BPP
+	// Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP.
 	ASTC10X6,
 
-	// ASTC 10x8 1.60 BPP
+	// Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP.
 	ASTC10X8,
 
-	// ASTC 10x10 1.28 BPP
+	// Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP.
 	ASTC10X10,
 
-	// ASTC 12x10 1.07 BPP
+	// Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP.
 	ASTC12X10,
 
-	// ASTC 12x12 0.89 BPP
+	// Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP.
 	ASTC12X12,
 
 	// Compressed formats above.
 	UNKNOWN,
+
+	// 1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP.
 	R1,
+
+	// 8-bit single-channel alpha, unsigned normalized. 8 BPP.
 	A8,
+
+	// 8-bit single-channel red, unsigned normalized. 8 BPP.
 	R8,
+
+	// 8-bit single-channel red, signed integer. 8 BPP.
 	R8I,
+
+	// 8-bit single-channel red, unsigned integer. 8 BPP.
 	R8U,
+
+	// 8-bit single-channel red, signed normalized. 8 BPP.
 	R8S,
+
+	// 16-bit single-channel red, unsigned normalized. 16 BPP.
 	R16,
+
+	// 16-bit single-channel red, signed integer. 16 BPP.
 	R16I,
+
+	// 16-bit single-channel red, unsigned integer. 16 BPP.
 	R16U,
+
+	// 16-bit single-channel red, half-precision floating point. 16 BPP.
 	R16F,
+
+	// 16-bit single-channel red, signed normalized. 16 BPP.
 	R16S,
+
+	// 32-bit single-channel red, signed integer. 32 BPP.
 	R32I,
+
+	// 32-bit single-channel red, unsigned integer. 32 BPP.
 	R32U,
+
+	// 32-bit single-channel red, full-precision floating point. 32 BPP.
 	R32F,
+
+	// Two 8-bit channels (red, green), unsigned normalized. 16 BPP.
 	RG8,
+
+	// Two 8-bit channels (red, green), signed integer. 16 BPP.
 	RG8I,
+
+	// Two 8-bit channels (red, green), unsigned integer. 16 BPP.
 	RG8U,
+
+	// Two 8-bit channels (red, green), signed normalized. 16 BPP.
 	RG8S,
+
+	// Two 16-bit channels (red, green), unsigned normalized. 32 BPP.
 	RG16,
+
+	// Two 16-bit channels (red, green), signed integer. 32 BPP.
 	RG16I,
+
+	// Two 16-bit channels (red, green), unsigned integer. 32 BPP.
 	RG16U,
+
+	// Two 16-bit channels (red, green), half-precision floating point. 32 BPP.
 	RG16F,
+
+	// Two 16-bit channels (red, green), signed normalized. 32 BPP.
 	RG16S,
+
+	// Two 32-bit channels (red, green), signed integer. 64 BPP.
 	RG32I,
+
+	// Two 32-bit channels (red, green), unsigned integer. 64 BPP.
 	RG32U,
+
+	// Two 32-bit channels (red, green), full-precision floating point. 64 BPP.
 	RG32F,
+
+	// Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP.
 	RGB8,
+
+	// Three 8-bit channels (red, green, blue), signed integer. 24 BPP.
 	RGB8I,
+
+	// Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP.
 	RGB8U,
+
+	// Three 8-bit channels (red, green, blue), signed normalized. 24 BPP.
 	RGB8S,
+
+	// Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP.
 	RGB9E5F,
+
+	// Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP.
 	BGRA8,
+
+	// Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP.
 	RGBA8,
+
+	// Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP.
 	RGBA8I,
+
+	// Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP.
 	RGBA8U,
+
+	// Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP.
 	RGBA8S,
+
+	// Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP.
 	RGBA16,
+
+	// Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP.
 	RGBA16I,
+
+	// Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP.
 	RGBA16U,
+
+	// Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP.
 	RGBA16F,
+
+	// Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP.
 	RGBA16S,
+
+	// Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP.
 	RGBA32I,
+
+	// Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP.
 	RGBA32U,
+
+	// Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP.
 	RGBA32F,
+
+	// Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP.
 	B5G6R5,
+
+	// Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP.
 	R5G6B5,
+
+	// Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP.
 	BGRA4,
+
+	// Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP.
 	RGBA4,
+
+	// Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP.
 	BGR5A1,
+
+	// Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP.
 	RGB5A1,
+
+	// Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP.
 	RGB10A2,
+
+	// Packed 32-bit, 11-bit red, 11-bit green, 10-bit blue, unsigned floating point. No alpha. 32 BPP.
 	RG11B10F,
 
 	// Depth formats below.
 	UNKNOWNDEPTH,
+
+	// 16-bit depth, unsigned normalized. 16 BPP.
 	D16,
+
+	// 24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP.
 	D24,
+
+	// 24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP.
 	D24S8,
+
+	// 32-bit depth, unsigned normalized. 32 BPP.
 	D32,
+
+	// 16-bit depth, floating point. 16 BPP.
 	D16F,
+
+	// 24-bit depth, floating point (stored as 32-bit). 32 BPP.
 	D24F,
+
+	// 32-bit depth, floating point. 32 BPP.
 	D32F,
+
+	// 8-bit stencil only, no depth. 8 BPP.
 	D0S8,
 
 	COUNT
@@ -2055,9 +2175,30 @@ extern fn void shutdown() @extern("bgfx_shutdown");
 // _format : `Texture format. See: `TextureFormat::Enum`.`
 extern fn void reset(uint _width, uint _height, uint _flags, TextureFormat _format) @extern("bgfx_reset");
 
-// Advance to next frame. When using multithreaded renderer, this call
+// Advance to next frame. This is the main frame-advancement call on the
-// just swaps internal buffers, kicks render thread, and returns. In
+// API thread (the thread from which `bgfx::init` was called).
-// singlethreaded renderer this call does frame rendering.
+// 
+// **Multithreaded renderer** (`BGFX_CONFIG_MULTITHREADED=1`, default):
+// This call waits for the render thread to finish processing the previous
+// frame, then swaps internal submit/render buffers, signals the render
+// thread to begin processing the new frame via `bgfx::renderFrame`, and
+// returns immediately. The render thread and API thread then run in
+// parallel: the API thread builds the next frame while the render thread
+// executes GPU commands for the current frame.
+// 
+// **Single-threaded renderer** (`BGFX_CONFIG_MULTITHREADED=0`, or when
+// `bgfx::renderFrame` and `bgfx::init` are called from the same thread):
+// This call swaps internal buffers and performs frame rendering inline
+// (internally calls `bgfx::renderFrame`), then returns.
+// 
+// @remarks
+//   Must be called from the API thread (the thread that called
+//   `bgfx::init`). In multithreaded mode, this call synchronizes with
+//   `bgfx::renderFrame` running on the render thread via semaphores:
+//   `bgfx::frame` waits for the render thread to finish, then posts a
+//   signal that `bgfx::renderFrame` waits on to begin the next frame.
+//   See also: `bgfx::renderFrame`.
+// 
 // _flags : `Frame flags. See: `BGFX_FRAME_*` for more info.   - `BGFX_FRAME_NONE` - No frame flag.   - `BGFX_FRAME_DEBUG_CAPTURE` - Capture frame with graphics debugger.   - `BGFX_FRAME_DISCARD` - Discard all draw calls.`
 extern fn uint frame(char _flags) @extern("bgfx_frame");
 
@@ -3103,16 +3244,43 @@ extern fn void encoder_blit(Encoder* _this, ushort _id, TextureHandle _dst, char
 // _filePath : `Will be passed to `bgfx::CallbackI::screenShot` callback.`
 extern fn void request_screen_shot(FrameBufferHandle _handle, ZString _filePath) @extern("bgfx_request_screen_shot");
 
-// Render frame.
+// Render frame. Executes the actual GPU rendering work for one frame.
 // 
-// @attention `bgfx::renderFrame` is blocking call. It waits for
+// In the default **multithreaded** configuration, `bgfx::renderFrame` runs
-//   `bgfx::frame` to be called from API thread to process frame.
+// on the **render thread** while `bgfx::frame` runs on the **API thread**.
-//   If timeout value is passed call will timeout and return even
+// Their interaction is as follows:
-//   if `bgfx::frame` is not called.
 // 
-// @warning This call should be only used on platforms that don't
+//   1. The render thread calls `bgfx::renderFrame`, which blocks waiting
-//   allow creating separate rendering thread. If it is called before
+//      for the API thread to signal that a new frame is ready.
-//   to bgfx::init, render thread won't be created by bgfx::init call.
+//   2. On the API thread, `bgfx::frame` finishes building the frame,
+//      swaps internal submit/render buffers, and signals the render thread.
+//   3. `bgfx::renderFrame` wakes up, executes pre-render commands,
+//      submits GPU draw calls, executes post-render commands, flips the
+//      back buffer, then signals back to the API thread that rendering
+//      is complete.
+//   4. The API thread's next `bgfx::frame` call waits for this completion
+//      signal before swapping buffers again.
+// 
+// This double-buffered semaphore handshake allows the API thread and
+// render thread to run in parallel, overlapping CPU frame building with
+// GPU rendering.
+// 
+// @attention `bgfx::renderFrame` is a blocking call. It waits for
+//   `bgfx::frame` to be called from the API thread to process the frame.
+//   If a timeout value is passed, the call will return
+//   `RenderFrame::Timeout` even if `bgfx::frame` has not been called.
+//   A value of -1 (default) means wait indefinitely (up to
+//   `BGFX_CONFIG_API_SEMAPHORE_TIMEOUT`).
+// 
+// @warning This call should only be used on platforms that don't allow
+//   creating a separate rendering thread. If it is called before
+//   `bgfx::init`, the internal render thread won't be created by the
+//   `bgfx::init` call, and the user is responsible for calling
+//   `bgfx::renderFrame` on the render thread each frame. If both
+//   `bgfx::renderFrame` and `bgfx::init` are called from the same
+//   thread, bgfx operates in single-threaded mode and `bgfx::frame`
+//   will internally invoke `bgfx::renderFrame` automatically.
+//   See also: `bgfx::frame`.
 // 
 // _msecs : `Timeout in milliseconds.`
 extern fn RenderFrame render_frame(int _msecs) @extern("bgfx_render_frame");

bindings/cs/bgfx.cs

@@ -1611,192 +1611,192 @@ public static partial class bgfx
 	public enum TextureFormat
 	{
 		/// <summary>
-		/// DXT1 R5G6B5A1
+		/// Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP.
 		/// </summary>
 		BC1,
 	
 		/// <summary>
-		/// DXT3 R5G6B5A4
+		/// Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP.
 		/// </summary>
 		BC2,
 	
 		/// <summary>
-		/// DXT5 R5G6B5A8
+		/// Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP.
 		/// </summary>
 		BC3,
 	
 		/// <summary>
-		/// LATC1/ATI1 R8
+		/// Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP.
 		/// </summary>
 		BC4,
 	
 		/// <summary>
-		/// LATC2/ATI2 RG8
+		/// Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP.
 		/// </summary>
 		BC5,
 	
 		/// <summary>
-		/// BC6H RGB16F
+		/// Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP.
 		/// </summary>
 		BC6H,
 	
 		/// <summary>
-		/// BC7 RGB 4-7 bits per color channel, 0-8 bits alpha
+		/// RGB 4-7 bits per color channel, 0-8 bits alpha. Block Compression 7. High-quality RGBA, 4-7 bits per color, 0-8 bits alpha. 8 BPP.
 		/// </summary>
 		BC7,
 	
 		/// <summary>
-		/// ETC1 RGB8
+		/// Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP.
 		/// </summary>
 		ETC1,
 	
 		/// <summary>
-		/// ETC2 RGB8
+		/// Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP.
 		/// </summary>
 		ETC2,
 	
 		/// <summary>
-		/// ETC2 RGBA8
+		/// Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP.
 		/// </summary>
 		ETC2A,
 	
 		/// <summary>
-		/// ETC2 RGB8A1
+		/// Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP.
 		/// </summary>
 		ETC2A1,
 	
 		/// <summary>
-		/// EAC R11 UNORM
+		/// ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP.
 		/// </summary>
 		EACR11,
 	
 		/// <summary>
-		/// EAC R11 SNORM
+		/// ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP.
 		/// </summary>
 		EACR11S,
 	
 		/// <summary>
-		/// EAC RG11 UNORM
+		/// ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP.
 		/// </summary>
 		EACRG11,
 	
 		/// <summary>
-		/// EAC RG11 SNORM
+		/// ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP.
 		/// </summary>
 		EACRG11S,
 	
 		/// <summary>
-		/// PVRTC1 RGB 2BPP
+		/// PowerVR Texture Compression v1. 3-channel RGB. 2 BPP.
 		/// </summary>
 		PTC12,
 	
 		/// <summary>
-		/// PVRTC1 RGB 4BPP
+		/// PowerVR Texture Compression v1. 3-channel RGB. 4 BPP.
 		/// </summary>
 		PTC14,
 	
 		/// <summary>
-		/// PVRTC1 RGBA 2BPP
+		/// PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP.
 		/// </summary>
 		PTC12A,
 	
 		/// <summary>
-		/// PVRTC1 RGBA 4BPP
+		/// PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP.
 		/// </summary>
 		PTC14A,
 	
 		/// <summary>
-		/// PVRTC2 RGBA 2BPP
+		/// PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP.
 		/// </summary>
 		PTC22,
 	
 		/// <summary>
-		/// PVRTC2 RGBA 4BPP
+		/// PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP.
 		/// </summary>
 		PTC24,
 	
 		/// <summary>
-		/// ATC RGB 4BPP
+		/// AMD Texture Compression. 3-channel RGB. 4 BPP.
 		/// </summary>
 		ATC,
 	
 		/// <summary>
-		/// ATCE RGBA 8 BPP explicit alpha
+		/// AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP.
 		/// </summary>
 		ATCE,
 	
 		/// <summary>
-		/// ATCI RGBA 8 BPP interpolated alpha
+		/// AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP.
 		/// </summary>
 		ATCI,
 	
 		/// <summary>
-		/// ASTC 4x4 8.0 BPP
+		/// Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP.
 		/// </summary>
 		ASTC4x4,
 	
 		/// <summary>
-		/// ASTC 5x4 6.40 BPP
+		/// Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP.
 		/// </summary>
 		ASTC5x4,
 	
 		/// <summary>
-		/// ASTC 5x5 5.12 BPP
+		/// Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP.
 		/// </summary>
 		ASTC5x5,
 	
 		/// <summary>
-		/// ASTC 6x5 4.27 BPP
+		/// Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP.
 		/// </summary>
 		ASTC6x5,
 	
 		/// <summary>
-		/// ASTC 6x6 3.56 BPP
+		/// Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP.
 		/// </summary>
 		ASTC6x6,
 	
 		/// <summary>
-		/// ASTC 8x5 3.20 BPP
+		/// Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP.
 		/// </summary>
 		ASTC8x5,
 	
 		/// <summary>
-		/// ASTC 8x6 2.67 BPP
+		/// Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP.
 		/// </summary>
 		ASTC8x6,
 	
 		/// <summary>
-		/// ASTC 8x8 2.00 BPP
+		/// Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP.
 		/// </summary>
 		ASTC8x8,
 	
 		/// <summary>
-		/// ASTC 10x5 2.56 BPP
+		/// Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP.
 		/// </summary>
 		ASTC10x5,
 	
 		/// <summary>
-		/// ASTC 10x6 2.13 BPP
+		/// Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP.
 		/// </summary>
 		ASTC10x6,
 	
 		/// <summary>
-		/// ASTC 10x8 1.60 BPP
+		/// Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP.
 		/// </summary>
 		ASTC10x8,
 	
 		/// <summary>
-		/// ASTC 10x10 1.28 BPP
+		/// Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP.
 		/// </summary>
 		ASTC10x10,
 	
 		/// <summary>
-		/// ASTC 12x10 1.07 BPP
+		/// Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP.
 		/// </summary>
 		ASTC12x10,
 	
 		/// <summary>
-		/// ASTC 12x12 0.89 BPP
+		/// Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP.
 		/// </summary>
 		ASTC12x12,
 	
@@ -1804,70 +1804,310 @@ public static partial class bgfx
 		/// Compressed formats above.
 		/// </summary>
 		Unknown,
+	
+		/// <summary>
+		/// 1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP.
+		/// </summary>
 		R1,
+	
+		/// <summary>
+		/// 8-bit single-channel alpha, unsigned normalized. 8 BPP.
+		/// </summary>
 		A8,
+	
+		/// <summary>
+		/// 8-bit single-channel red, unsigned normalized. 8 BPP.
+		/// </summary>
 		R8,
+	
+		/// <summary>
+		/// 8-bit single-channel red, signed integer. 8 BPP.
+		/// </summary>
 		R8I,
+	
+		/// <summary>
+		/// 8-bit single-channel red, unsigned integer. 8 BPP.
+		/// </summary>
 		R8U,
+	
+		/// <summary>
+		/// 8-bit single-channel red, signed normalized. 8 BPP.
+		/// </summary>
 		R8S,
+	
+		/// <summary>
+		/// 16-bit single-channel red, unsigned normalized. 16 BPP.
+		/// </summary>
 		R16,
+	
+		/// <summary>
+		/// 16-bit single-channel red, signed integer. 16 BPP.
+		/// </summary>
 		R16I,
+	
+		/// <summary>
+		/// 16-bit single-channel red, unsigned integer. 16 BPP.
+		/// </summary>
 		R16U,
+	
+		/// <summary>
+		/// 16-bit single-channel red, half-precision floating point. 16 BPP.
+		/// </summary>
 		R16F,
+	
+		/// <summary>
+		/// 16-bit single-channel red, signed normalized. 16 BPP.
+		/// </summary>
 		R16S,
+	
+		/// <summary>
+		/// 32-bit single-channel red, signed integer. 32 BPP.
+		/// </summary>
 		R32I,
+	
+		/// <summary>
+		/// 32-bit single-channel red, unsigned integer. 32 BPP.
+		/// </summary>
 		R32U,
+	
+		/// <summary>
+		/// 32-bit single-channel red, full-precision floating point. 32 BPP.
+		/// </summary>
 		R32F,
+	
+		/// <summary>
+		/// Two 8-bit channels (red, green), unsigned normalized. 16 BPP.
+		/// </summary>
 		RG8,
+	
+		/// <summary>
+		/// Two 8-bit channels (red, green), signed integer. 16 BPP.
+		/// </summary>
 		RG8I,
+	
+		/// <summary>
+		/// Two 8-bit channels (red, green), unsigned integer. 16 BPP.
+		/// </summary>
 		RG8U,
+	
+		/// <summary>
+		/// Two 8-bit channels (red, green), signed normalized. 16 BPP.
+		/// </summary>
 		RG8S,
+	
+		/// <summary>
+		/// Two 16-bit channels (red, green), unsigned normalized. 32 BPP.
+		/// </summary>
 		RG16,
+	
+		/// <summary>
+		/// Two 16-bit channels (red, green), signed integer. 32 BPP.
+		/// </summary>
 		RG16I,
+	
+		/// <summary>
+		/// Two 16-bit channels (red, green), unsigned integer. 32 BPP.
+		/// </summary>
 		RG16U,
+	
+		/// <summary>
+		/// Two 16-bit channels (red, green), half-precision floating point. 32 BPP.
+		/// </summary>
 		RG16F,
+	
+		/// <summary>
+		/// Two 16-bit channels (red, green), signed normalized. 32 BPP.
+		/// </summary>
 		RG16S,
+	
+		/// <summary>
+		/// Two 32-bit channels (red, green), signed integer. 64 BPP.
+		/// </summary>
 		RG32I,
+	
+		/// <summary>
+		/// Two 32-bit channels (red, green), unsigned integer. 64 BPP.
+		/// </summary>
 		RG32U,
+	
+		/// <summary>
+		/// Two 32-bit channels (red, green), full-precision floating point. 64 BPP.
+		/// </summary>
 		RG32F,
+	
+		/// <summary>
+		/// Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP.
+		/// </summary>
 		RGB8,
+	
+		/// <summary>
+		/// Three 8-bit channels (red, green, blue), signed integer. 24 BPP.
+		/// </summary>
 		RGB8I,
+	
+		/// <summary>
+		/// Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP.
+		/// </summary>
 		RGB8U,
+	
+		/// <summary>
+		/// Three 8-bit channels (red, green, blue), signed normalized. 24 BPP.
+		/// </summary>
 		RGB8S,
+	
+		/// <summary>
+		/// Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP.
+		/// </summary>
 		RGB9E5F,
+	
+		/// <summary>
+		/// Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP.
+		/// </summary>
 		BGRA8,
+	
+		/// <summary>
+		/// Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP.
+		/// </summary>
 		RGBA8,
+	
+		/// <summary>
+		/// Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP.
+		/// </summary>
 		RGBA8I,
+	
+		/// <summary>
+		/// Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP.
+		/// </summary>
 		RGBA8U,
+	
+		/// <summary>
+		/// Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP.
+		/// </summary>
 		RGBA8S,
+	
+		/// <summary>
+		/// Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP.
+		/// </summary>
 		RGBA16,
+	
+		/// <summary>
+		/// Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP.
+		/// </summary>
 		RGBA16I,
+	
+		/// <summary>
+		/// Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP.
+		/// </summary>
 		RGBA16U,
+	
+		/// <summary>
+		/// Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP.
+		/// </summary>
 		RGBA16F,
+	
+		/// <summary>
+		/// Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP.
+		/// </summary>
 		RGBA16S,
+	
+		/// <summary>
+		/// Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP.
+		/// </summary>
 		RGBA32I,
+	
+		/// <summary>
+		/// Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP.
+		/// </summary>
 		RGBA32U,
+	
+		/// <summary>
+		/// Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP.
+		/// </summary>
 		RGBA32F,
+	
+		/// <summary>
+		/// Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP.
+		/// </summary>
 		B5G6R5,
+	
+		/// <summary>
+		/// Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP.
+		/// </summary>
 		R5G6B5,
+	
+		/// <summary>
+		/// Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP.
+		/// </summary>
 		BGRA4,
+	
+		/// <summary>
+		/// Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP.
+		/// </summary>
 		RGBA4,
+	
+		/// <summary>
+		/// Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP.
+		/// </summary>
 		BGR5A1,
+	
+		/// <summary>
+		/// Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP.
+		/// </summary>
 		RGB5A1,
+	
+		/// <summary>
+		/// Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP.
+		/// </summary>
 		RGB10A2,
+	
+		/// <summary>
+		/// Packed 32-bit, 11-bit red, 11-bit green, 10-bit blue, unsigned floating point. No alpha. 32 BPP.
+		/// </summary>
 		RG11B10F,
 	
 		/// <summary>
 		/// Depth formats below.
 		/// </summary>
 		UnknownDepth,
+	
+		/// <summary>
+		/// 16-bit depth, unsigned normalized. 16 BPP.
+		/// </summary>
 		D16,
+	
+		/// <summary>
+		/// 24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP.
+		/// </summary>
 		D24,
+	
+		/// <summary>
+		/// 24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP.
+		/// </summary>
 		D24S8,
+	
+		/// <summary>
+		/// 32-bit depth, unsigned normalized. 32 BPP.
+		/// </summary>
 		D32,
+	
+		/// <summary>
+		/// 16-bit depth, floating point. 16 BPP.
+		/// </summary>
 		D16F,
+	
+		/// <summary>
+		/// 24-bit depth, floating point (stored as 32-bit). 32 BPP.
+		/// </summary>
 		D24F,
+	
+		/// <summary>
+		/// 32-bit depth, floating point. 32 BPP.
+		/// </summary>
 		D32F,
+	
+		/// <summary>
+		/// 8-bit stencil only, no depth. 8 BPP.
+		/// </summary>
 		D0S8,
 	
 		Count
@@ -2685,9 +2925,30 @@ public static partial class bgfx
 	public static extern unsafe void reset(uint _width, uint _height, uint _flags, TextureFormat _format);
 	
 	/// <summary>
-	/// Advance to next frame. When using multithreaded renderer, this call
+	/// Advance to next frame. This is the main frame-advancement call on the
-	/// just swaps internal buffers, kicks render thread, and returns. In
+	/// API thread (the thread from which `bgfx::init` was called).
-	/// singlethreaded renderer this call does frame rendering.
+	/// 
+	/// **Multithreaded renderer** (`BGFX_CONFIG_MULTITHREADED=1`, default):
+	/// This call waits for the render thread to finish processing the previous
+	/// frame, then swaps internal submit/render buffers, signals the render
+	/// thread to begin processing the new frame via `bgfx::renderFrame`, and
+	/// returns immediately. The render thread and API thread then run in
+	/// parallel: the API thread builds the next frame while the render thread
+	/// executes GPU commands for the current frame.
+	/// 
+	/// **Single-threaded renderer** (`BGFX_CONFIG_MULTITHREADED=0`, or when
+	/// `bgfx::renderFrame` and `bgfx::init` are called from the same thread):
+	/// This call swaps internal buffers and performs frame rendering inline
+	/// (internally calls `bgfx::renderFrame`), then returns.
+	/// 
+	/// @remarks
+	///   Must be called from the API thread (the thread that called
+	///   `bgfx::init`). In multithreaded mode, this call synchronizes with
+	///   `bgfx::renderFrame` running on the render thread via semaphores:
+	///   `bgfx::frame` waits for the render thread to finish, then posts a
+	///   signal that `bgfx::renderFrame` waits on to begin the next frame.
+	///   See also: `bgfx::renderFrame`.
+	/// 
 	/// </summary>
 	///
 	/// <param name="_flags">Frame flags. See: `BGFX_FRAME_*` for more info.   - `BGFX_FRAME_NONE` - No frame flag.   - `BGFX_FRAME_DEBUG_CAPTURE` - Capture frame with graphics debugger.   - `BGFX_FRAME_DISCARD` - Discard all draw calls.</param>
@@ -4407,16 +4668,43 @@ public static partial class bgfx
 	public static extern unsafe void request_screen_shot(FrameBufferHandle _handle, [MarshalAs(UnmanagedType.LPStr)] string _filePath);
 	
 	/// <summary>
-	/// Render frame.
+	/// Render frame. Executes the actual GPU rendering work for one frame.
 	/// 
-	/// @attention `bgfx::renderFrame` is blocking call. It waits for
+	/// In the default **multithreaded** configuration, `bgfx::renderFrame` runs
-	///   `bgfx::frame` to be called from API thread to process frame.
+	/// on the **render thread** while `bgfx::frame` runs on the **API thread**.
-	///   If timeout value is passed call will timeout and return even
+	/// Their interaction is as follows:
-	///   if `bgfx::frame` is not called.
 	/// 
-	/// @warning This call should be only used on platforms that don't
+	///   1. The render thread calls `bgfx::renderFrame`, which blocks waiting
-	///   allow creating separate rendering thread. If it is called before
+	///      for the API thread to signal that a new frame is ready.
-	///   to bgfx::init, render thread won't be created by bgfx::init call.
+	///   2. On the API thread, `bgfx::frame` finishes building the frame,
+	///      swaps internal submit/render buffers, and signals the render thread.
+	///   3. `bgfx::renderFrame` wakes up, executes pre-render commands,
+	///      submits GPU draw calls, executes post-render commands, flips the
+	///      back buffer, then signals back to the API thread that rendering
+	///      is complete.
+	///   4. The API thread's next `bgfx::frame` call waits for this completion
+	///      signal before swapping buffers again.
+	/// 
+	/// This double-buffered semaphore handshake allows the API thread and
+	/// render thread to run in parallel, overlapping CPU frame building with
+	/// GPU rendering.
+	/// 
+	/// @attention `bgfx::renderFrame` is a blocking call. It waits for
+	///   `bgfx::frame` to be called from the API thread to process the frame.
+	///   If a timeout value is passed, the call will return
+	///   `RenderFrame::Timeout` even if `bgfx::frame` has not been called.
+	///   A value of -1 (default) means wait indefinitely (up to
+	///   `BGFX_CONFIG_API_SEMAPHORE_TIMEOUT`).
+	/// 
+	/// @warning This call should only be used on platforms that don't allow
+	///   creating a separate rendering thread. If it is called before
+	///   `bgfx::init`, the internal render thread won't be created by the
+	///   `bgfx::init` call, and the user is responsible for calling
+	///   `bgfx::renderFrame` on the render thread each frame. If both
+	///   `bgfx::renderFrame` and `bgfx::init` are called from the same
+	///   thread, bgfx operates in single-threaded mode and `bgfx::frame`
+	///   will internally invoke `bgfx::renderFrame` automatically.
+	///   See also: `bgfx::frame`.
 	/// 
 	/// </summary>
 	///

bindings/d/package.d

@@ -2117,9 +2117,30 @@ mixin(joinFnBinds((){
 		{q{void}, q{reset}, q{uint width, uint height, uint flags=Reset.none, bgfx.impl.TextureFormat.Enum format=TextureFormat.count}, ext: `C++, "bgfx"`},
 		
 		/**
-		* Advance to next frame. When using multithreaded renderer, this call
+		* Advance to next frame. This is the main frame-advancement call on the
-		* just swaps internal buffers, kicks render thread, and returns. In
+		* API thread (the thread from which `bgfx::init` was called).
-		* singlethreaded renderer this call does frame rendering.
+		* 
+		* **Multithreaded renderer** (`BGFX_CONFIG_MULTITHREADED=1`, default):
+		* This call waits for the render thread to finish processing the previous
+		* frame, then swaps internal submit/render buffers, signals the render
+		* thread to begin processing the new frame via `bgfx::renderFrame`, and
+		* returns immediately. The render thread and API thread then run in
+		* parallel: the API thread builds the next frame while the render thread
+		* executes GPU commands for the current frame.
+		* 
+		* **Single-threaded renderer** (`BGFX_CONFIG_MULTITHREADED=0`, or when
+		* `bgfx::renderFrame` and `bgfx::init` are called from the same thread):
+		* This call swaps internal buffers and performs frame rendering inline
+		* (internally calls `bgfx::renderFrame`), then returns.
+		* 
+		* Remarks:
+		*   Must be called from the API thread (the thread that called
+		*   `bgfx::init`). In multithreaded mode, this call synchronizes with
+		*   `bgfx::renderFrame` running on the render thread via semaphores:
+		*   `bgfx::frame` waits for the render thread to finish, then posts a
+		*   signal that `bgfx::renderFrame` waits on to begin the next frame.
+		*   See also: `bgfx::renderFrame`.
+		* 
 		Params:
 			flags = Frame flags. See: `BGFX_FRAME_*` for more info.
 		  - `BGFX_FRAME_NONE` - No frame flag.
@@ -3265,16 +3286,43 @@ mixin(joinFnBinds((){
 		{q{void}, q{requestScreenShot}, q{FrameBufferHandle handle, const(char)* filePath}, ext: `C++, "bgfx"`},
 		
 		/**
-		* Render frame.
+		* Render frame. Executes the actual GPU rendering work for one frame.
 		* 
-		* Attention: `bgfx::renderFrame` is blocking call. It waits for
+		* In the default **multithreaded** configuration, `bgfx::renderFrame` runs
-		*   `bgfx::frame` to be called from API thread to process frame.
+		* on the **render thread** while `bgfx::frame` runs on the **API thread**.
-		*   If timeout value is passed call will timeout and return even
+		* Their interaction is as follows:
-		*   if `bgfx::frame` is not called.
 		* 
-		* Warning: This call should be only used on platforms that don't
+		*   1. The render thread calls `bgfx::renderFrame`, which blocks waiting
-		*   allow creating separate rendering thread. If it is called before
+		*      for the API thread to signal that a new frame is ready.
-		*   to bgfx::init, render thread won't be created by bgfx::init call.
+		*   2. On the API thread, `bgfx::frame` finishes building the frame,
+		*      swaps internal submit/render buffers, and signals the render thread.
+		*   3. `bgfx::renderFrame` wakes up, executes pre-render commands,
+		*      submits GPU draw calls, executes post-render commands, flips the
+		*      back buffer, then signals back to the API thread that rendering
+		*      is complete.
+		*   4. The API thread's next `bgfx::frame` call waits for this completion
+		*      signal before swapping buffers again.
+		* 
+		* This double-buffered semaphore handshake allows the API thread and
+		* render thread to run in parallel, overlapping CPU frame building with
+		* GPU rendering.
+		* 
+		* Attention: `bgfx::renderFrame` is a blocking call. It waits for
+		*   `bgfx::frame` to be called from the API thread to process the frame.
+		*   If a timeout value is passed, the call will return
+		*   `RenderFrame::Timeout` even if `bgfx::frame` has not been called.
+		*   A value of -1 (default) means wait indefinitely (up to
+		*   `BGFX_CONFIG_API_SEMAPHORE_TIMEOUT`).
+		* 
+		* Warning: This call should only be used on platforms that don't allow
+		*   creating a separate rendering thread. If it is called before
+		*   `bgfx::init`, the internal render thread won't be created by the
+		*   `bgfx::init` call, and the user is responsible for calling
+		*   `bgfx::renderFrame` on the render thread each frame. If both
+		*   `bgfx::renderFrame` and `bgfx::init` are called from the same
+		*   thread, bgfx operates in single-threaded mode and `bgfx::frame`
+		*   will internally invoke `bgfx::renderFrame` automatically.
+		*   See also: `bgfx::frame`.
 		* 
 		Params:
 			msecs = Timeout in milliseconds.

bindings/zig/bgfx.zig

@@ -986,184 +986,304 @@ pub const AttribType = enum(c_int) {
 };
 
 pub const TextureFormat = enum(c_int) {
-    /// DXT1 R5G6B5A1
+    /// Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP.
     BC1,
 
-    /// DXT3 R5G6B5A4
+    /// Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP.
     BC2,
 
-    /// DXT5 R5G6B5A8
+    /// Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP.
     BC3,
 
-    /// LATC1/ATI1 R8
+    /// Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP.
     BC4,
 
-    /// LATC2/ATI2 RG8
+    /// Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP.
     BC5,
 
-    /// BC6H RGB16F
+    /// Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP.
     BC6H,
 
-    /// BC7 RGB 4-7 bits per color channel, 0-8 bits alpha
+    /// RGB 4-7 bits per color channel, 0-8 bits alpha. Block Compression 7. High-quality RGBA, 4-7 bits per color, 0-8 bits alpha. 8 BPP.
     BC7,
 
-    /// ETC1 RGB8
+    /// Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP.
     ETC1,
 
-    /// ETC2 RGB8
+    /// Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP.
     ETC2,
 
-    /// ETC2 RGBA8
+    /// Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP.
     ETC2A,
 
-    /// ETC2 RGB8A1
+    /// Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP.
     ETC2A1,
 
-    /// EAC R11 UNORM
+    /// ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP.
     EACR11,
 
-    /// EAC R11 SNORM
+    /// ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP.
     EACR11S,
 
-    /// EAC RG11 UNORM
+    /// ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP.
     EACRG11,
 
-    /// EAC RG11 SNORM
+    /// ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP.
     EACRG11S,
 
-    /// PVRTC1 RGB 2BPP
+    /// PowerVR Texture Compression v1. 3-channel RGB. 2 BPP.
     PTC12,
 
-    /// PVRTC1 RGB 4BPP
+    /// PowerVR Texture Compression v1. 3-channel RGB. 4 BPP.
     PTC14,
 
-    /// PVRTC1 RGBA 2BPP
+    /// PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP.
     PTC12A,
 
-    /// PVRTC1 RGBA 4BPP
+    /// PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP.
     PTC14A,
 
-    /// PVRTC2 RGBA 2BPP
+    /// PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP.
     PTC22,
 
-    /// PVRTC2 RGBA 4BPP
+    /// PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP.
     PTC24,
 
-    /// ATC RGB 4BPP
+    /// AMD Texture Compression. 3-channel RGB. 4 BPP.
     ATC,
 
-    /// ATCE RGBA 8 BPP explicit alpha
+    /// AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP.
     ATCE,
 
-    /// ATCI RGBA 8 BPP interpolated alpha
+    /// AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP.
     ATCI,
 
-    /// ASTC 4x4 8.0 BPP
+    /// Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP.
     ASTC4x4,
 
-    /// ASTC 5x4 6.40 BPP
+    /// Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP.
     ASTC5x4,
 
-    /// ASTC 5x5 5.12 BPP
+    /// Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP.
     ASTC5x5,
 
-    /// ASTC 6x5 4.27 BPP
+    /// Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP.
     ASTC6x5,
 
-    /// ASTC 6x6 3.56 BPP
+    /// Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP.
     ASTC6x6,
 
-    /// ASTC 8x5 3.20 BPP
+    /// Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP.
     ASTC8x5,
 
-    /// ASTC 8x6 2.67 BPP
+    /// Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP.
     ASTC8x6,
 
-    /// ASTC 8x8 2.00 BPP
+    /// Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP.
     ASTC8x8,
 
-    /// ASTC 10x5 2.56 BPP
+    /// Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP.
     ASTC10x5,
 
-    /// ASTC 10x6 2.13 BPP
+    /// Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP.
     ASTC10x6,
 
-    /// ASTC 10x8 1.60 BPP
+    /// Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP.
     ASTC10x8,
 
-    /// ASTC 10x10 1.28 BPP
+    /// Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP.
     ASTC10x10,
 
-    /// ASTC 12x10 1.07 BPP
+    /// Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP.
     ASTC12x10,
 
-    /// ASTC 12x12 0.89 BPP
+    /// Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP.
     ASTC12x12,
 
     /// Compressed formats above.
     Unknown,
+
+    /// 1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP.
     R1,
+
+    /// 8-bit single-channel alpha, unsigned normalized. 8 BPP.
     A8,
+
+    /// 8-bit single-channel red, unsigned normalized. 8 BPP.
     R8,
+
+    /// 8-bit single-channel red, signed integer. 8 BPP.
     R8I,
+
+    /// 8-bit single-channel red, unsigned integer. 8 BPP.
     R8U,
+
+    /// 8-bit single-channel red, signed normalized. 8 BPP.
     R8S,
+
+    /// 16-bit single-channel red, unsigned normalized. 16 BPP.
     R16,
+
+    /// 16-bit single-channel red, signed integer. 16 BPP.
     R16I,
+
+    /// 16-bit single-channel red, unsigned integer. 16 BPP.
     R16U,
+
+    /// 16-bit single-channel red, half-precision floating point. 16 BPP.
     R16F,
+
+    /// 16-bit single-channel red, signed normalized. 16 BPP.
     R16S,
+
+    /// 32-bit single-channel red, signed integer. 32 BPP.
     R32I,
+
+    /// 32-bit single-channel red, unsigned integer. 32 BPP.
     R32U,
+
+    /// 32-bit single-channel red, full-precision floating point. 32 BPP.
     R32F,
+
+    /// Two 8-bit channels (red, green), unsigned normalized. 16 BPP.
     RG8,
+
+    /// Two 8-bit channels (red, green), signed integer. 16 BPP.
     RG8I,
+
+    /// Two 8-bit channels (red, green), unsigned integer. 16 BPP.
     RG8U,
+
+    /// Two 8-bit channels (red, green), signed normalized. 16 BPP.
     RG8S,
+
+    /// Two 16-bit channels (red, green), unsigned normalized. 32 BPP.
     RG16,
+
+    /// Two 16-bit channels (red, green), signed integer. 32 BPP.
     RG16I,
+
+    /// Two 16-bit channels (red, green), unsigned integer. 32 BPP.
     RG16U,
+
+    /// Two 16-bit channels (red, green), half-precision floating point. 32 BPP.
     RG16F,
+
+    /// Two 16-bit channels (red, green), signed normalized. 32 BPP.
     RG16S,
+
+    /// Two 32-bit channels (red, green), signed integer. 64 BPP.
     RG32I,
+
+    /// Two 32-bit channels (red, green), unsigned integer. 64 BPP.
     RG32U,
+
+    /// Two 32-bit channels (red, green), full-precision floating point. 64 BPP.
     RG32F,
+
+    /// Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP.
     RGB8,
+
+    /// Three 8-bit channels (red, green, blue), signed integer. 24 BPP.
     RGB8I,
+
+    /// Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP.
     RGB8U,
+
+    /// Three 8-bit channels (red, green, blue), signed normalized. 24 BPP.
     RGB8S,
+
+    /// Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP.
     RGB9E5F,
+
+    /// Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP.
     BGRA8,
+
+    /// Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP.
     RGBA8,
+
+    /// Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP.
     RGBA8I,
+
+    /// Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP.
     RGBA8U,
+
+    /// Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP.
     RGBA8S,
+
+    /// Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP.
     RGBA16,
+
+    /// Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP.
     RGBA16I,
+
+    /// Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP.
     RGBA16U,
+
+    /// Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP.
     RGBA16F,
+
+    /// Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP.
     RGBA16S,
+
+    /// Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP.
     RGBA32I,
+
+    /// Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP.
     RGBA32U,
+
+    /// Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP.
     RGBA32F,
+
+    /// Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP.
     B5G6R5,
+
+    /// Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP.
     R5G6B5,
+
+    /// Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP.
     BGRA4,
+
+    /// Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP.
     RGBA4,
+
+    /// Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP.
     BGR5A1,
+
+    /// Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP.
     RGB5A1,
+
+    /// Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP.
     RGB10A2,
+
+    /// Packed 32-bit, 11-bit red, 11-bit green, 10-bit blue, unsigned floating point. No alpha. 32 BPP.
     RG11B10F,
 
     /// Depth formats below.
     UnknownDepth,
+
+    /// 16-bit depth, unsigned normalized. 16 BPP.
     D16,
+
+    /// 24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP.
     D24,
+
+    /// 24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP.
     D24S8,
+
+    /// 32-bit depth, unsigned normalized. 32 BPP.
     D32,
+
+    /// 16-bit depth, floating point. 16 BPP.
     D16F,
+
+    /// 24-bit depth, floating point (stored as 32-bit). 32 BPP.
     D24F,
+
+    /// 32-bit depth, floating point. 32 BPP.
     D32F,
+
+    /// 8-bit stencil only, no depth. 8 BPP.
     D0S8,
 
     Count
@@ -2198,9 +2318,30 @@ pub inline fn reset(_width: u32, _height: u32, _flags: u32, _format: TextureForm
 }
 extern fn bgfx_reset(_width: u32, _height: u32, _flags: u32, _format: TextureFormat) void;
 
-/// Advance to next frame. When using multithreaded renderer, this call
+/// Advance to next frame. This is the main frame-advancement call on the
-/// just swaps internal buffers, kicks render thread, and returns. In
+/// API thread (the thread from which `bgfx::init` was called).
-/// singlethreaded renderer this call does frame rendering.
+/// 
+/// **Multithreaded renderer** (`BGFX_CONFIG_MULTITHREADED=1`, default):
+/// This call waits for the render thread to finish processing the previous
+/// frame, then swaps internal submit/render buffers, signals the render
+/// thread to begin processing the new frame via `bgfx::renderFrame`, and
+/// returns immediately. The render thread and API thread then run in
+/// parallel: the API thread builds the next frame while the render thread
+/// executes GPU commands for the current frame.
+/// 
+/// **Single-threaded renderer** (`BGFX_CONFIG_MULTITHREADED=0`, or when
+/// `bgfx::renderFrame` and `bgfx::init` are called from the same thread):
+/// This call swaps internal buffers and performs frame rendering inline
+/// (internally calls `bgfx::renderFrame`), then returns.
+/// 
+/// @remarks
+///   Must be called from the API thread (the thread that called
+///   `bgfx::init`). In multithreaded mode, this call synchronizes with
+///   `bgfx::renderFrame` running on the render thread via semaphores:
+///   `bgfx::frame` waits for the render thread to finish, then posts a
+///   signal that `bgfx::renderFrame` waits on to begin the next frame.
+///   See also: `bgfx::renderFrame`.
+/// 
 /// <param name="_flags">Frame flags. See: `BGFX_FRAME_*` for more info.   - `BGFX_FRAME_NONE` - No frame flag.   - `BGFX_FRAME_DEBUG_CAPTURE` - Capture frame with graphics debugger.   - `BGFX_FRAME_DISCARD` - Discard all draw calls.</param>
 pub inline fn frame(_flags: u8) u32 {
     return bgfx_frame(_flags);
@@ -3510,16 +3651,43 @@ pub inline fn requestScreenShot(_handle: FrameBufferHandle, _filePath: [*c]const
 }
 extern fn bgfx_request_screen_shot(_handle: FrameBufferHandle, _filePath: [*c]const u8) void;
 
-/// Render frame.
+/// Render frame. Executes the actual GPU rendering work for one frame.
 /// 
-/// @attention `bgfx::renderFrame` is blocking call. It waits for
+/// In the default **multithreaded** configuration, `bgfx::renderFrame` runs
-///   `bgfx::frame` to be called from API thread to process frame.
+/// on the **render thread** while `bgfx::frame` runs on the **API thread**.
-///   If timeout value is passed call will timeout and return even
+/// Their interaction is as follows:
-///   if `bgfx::frame` is not called.
 /// 
-/// @warning This call should be only used on platforms that don't
+///   1. The render thread calls `bgfx::renderFrame`, which blocks waiting
-///   allow creating separate rendering thread. If it is called before
+///      for the API thread to signal that a new frame is ready.
-///   to bgfx::init, render thread won't be created by bgfx::init call.
+///   2. On the API thread, `bgfx::frame` finishes building the frame,
+///      swaps internal submit/render buffers, and signals the render thread.
+///   3. `bgfx::renderFrame` wakes up, executes pre-render commands,
+///      submits GPU draw calls, executes post-render commands, flips the
+///      back buffer, then signals back to the API thread that rendering
+///      is complete.
+///   4. The API thread's next `bgfx::frame` call waits for this completion
+///      signal before swapping buffers again.
+/// 
+/// This double-buffered semaphore handshake allows the API thread and
+/// render thread to run in parallel, overlapping CPU frame building with
+/// GPU rendering.
+/// 
+/// @attention `bgfx::renderFrame` is a blocking call. It waits for
+///   `bgfx::frame` to be called from the API thread to process the frame.
+///   If a timeout value is passed, the call will return
+///   `RenderFrame::Timeout` even if `bgfx::frame` has not been called.
+///   A value of -1 (default) means wait indefinitely (up to
+///   `BGFX_CONFIG_API_SEMAPHORE_TIMEOUT`).
+/// 
+/// @warning This call should only be used on platforms that don't allow
+///   creating a separate rendering thread. If it is called before
+///   `bgfx::init`, the internal render thread won't be created by the
+///   `bgfx::init` call, and the user is responsible for calling
+///   `bgfx::renderFrame` on the render thread each frame. If both
+///   `bgfx::renderFrame` and `bgfx::init` are called from the same
+///   thread, bgfx operates in single-threaded mode and `bgfx::frame`
+///   will internally invoke `bgfx::renderFrame` automatically.
+///   See also: `bgfx::frame`.
 /// 
 /// <param name="_msecs">Timeout in milliseconds.</param>
 pub inline fn renderFrame(_msecs: i32) RenderFrame {

docs/bgfx.rst

@@ -1,3 +1,5 @@
+.. AUTO GENERATED! DO NOT EDIT!
+
 API Reference
 =============
 

docs/idl.rst

@@ -0,0 +1,261 @@
+IDL — Interface Definition Language
+====================================
+
+bgfx uses a custom Interface Definition Language (IDL) to define its entire public API in a single
+source-of-truth file: ``scripts/bgfx.idl``. From this file, code generators produce the C99 API,
+C++ API, language bindings, and documentation — ensuring that all representations stay in sync.
+
+For additional background and motivation, see the blog post:
+`IDL — Interface Definition Language <https://bkaradzic.github.io/posts/idl/>`__.
+
+Purpose
+-------
+
+The IDL serves several goals:
+
+- **Single source of truth** — The API (types, functions, flags, enums, structs, handles) is
+  declared once in ``bgfx.idl``. All generated outputs derive from this file.
+- **Multi-language bindings** — Code generators read the IDL and produce bindings for C99, C#, D,
+  Zig, Beef, C3, and potentially other languages.
+- **Documentation generation** — The ``docs-rst.lua`` generator produces reStructuredText API
+  reference documentation from the IDL.
+- **Consistency** — Changes to the API only need to be made in one place. The code generators
+  ensure that all bindings and documentation are updated automatically.
+
+File overview
+-------------
+
+All IDL-related files live under ``scripts/``:
+
+``bgfx.idl``
+    The IDL source file. Contains all type definitions, function declarations, flag/enum
+    definitions, struct layouts, handle types, documentation comments, and the section hierarchy
+    for the generated docs.
+
+``idl.lua``
+    The IDL parser/runtime. Sets up the Lua environment that ``bgfx.idl`` executes in. Provides
+    the DSL keywords (``typedef``, ``enum``, ``flag``, ``struct``, ``handle``, ``func``,
+    ``funcptr``, ``section``, ``version``, etc.) as Lua metatable-driven constructors.
+
+``codegen.lua``
+    Shared code generation utilities. Reads the parsed IDL, resolves types, converts between
+    naming conventions (CamelCase ↔ underscore_case), and provides template expansion for
+    function signatures.
+
+``bgfx-codegen.lua``
+    The main code generator. Reads the IDL via ``codegen.lua`` and produces the C99 header,
+    C++ header, C99-to-C++ bridge implementation, and the internal function ID tables.
+
+``bindings-*.lua``
+    Per-language binding generators (``bindings-cs.lua``, ``bindings-d.lua``, ``bindings-zig.lua``,
+    ``bindings-bf.lua``, ``bindings-c3.lua``). Each reads the IDL and outputs the API in the
+    target language's syntax and conventions.
+
+``docs-rst.lua``
+    Generates reStructuredText API reference documentation (``docs/bgfx.rst``) from the IDL.
+
+Running the code generators
+----------------------------
+
+The code generators are invoked via the makefile at the repository root:
+
+.. code-block:: bash
+
+    make idl
+
+This runs the Lua scripts that regenerate all C/C++ headers, language bindings, and documentation
+from ``scripts/bgfx.idl``.
+
+IDL syntax reference
+---------------------
+
+The IDL file is valid Lua, executed in a special environment that provides the DSL keywords.
+Comments prefixed with ``---`` become documentation comments attached to the next declaration.
+
+version
+~~~~~~~
+
+Declares the API version number:
+
+.. code-block:: lua
+
+    version(140)
+
+typedef
+~~~~~~~
+
+Declares a type alias. These map IDL type names to their C/C++ equivalents:
+
+.. code-block:: lua
+
+    typedef "uint32_t"
+    typedef "ViewId"
+    typedef "CallbackI" { cname = "callback_interface" }
+
+The optional table provides attributes. ``cname`` overrides the C binding name.
+
+handle
+~~~~~~
+
+Declares an opaque handle type. Handles are type-safe 16-bit integers used to reference GPU
+resources:
+
+.. code-block:: lua
+
+    handle "TextureHandle"
+    handle "VertexBufferHandle"
+
+enum
+~~~~
+
+Declares an enumeration. Each member can have a ``---`` documentation comment:
+
+.. code-block:: lua
+
+    enum.TextureFormat { comment = "Texture formats:", section = "Textures" }
+        .BC1       --- DXT1 R5G6B5A1.
+        .BC2       --- DXT3 R5G6B5A4.
+        .Unknown   --- Compressed formats above.
+        ()
+
+The ``()`` sentinel marks the end of the enum (generates a ``Count`` member). The ``section``
+attribute controls where this type appears in the generated documentation hierarchy.
+
+flag
+~~~~
+
+Declares a bitfield flag type. Similar to ``enum``, but members represent individual bits:
+
+.. code-block:: lua
+
+    flag.StateWrite { bits = 64, base = 1, section = "State Flags", label = "Write" }
+        .R     --- Enable R write.
+        .G     --- Enable G write.
+        .B     --- Enable B write.
+        .A     --- Enable alpha write.
+        .Z (39) --- Enable depth write.
+        .Rgb  { "R",   "G", "B" }  --- Enable RGB write.
+        .Mask { "Rgb", "A", "Z" }  --- Write all channels mask.
+
+Attributes:
+
+- ``bits`` — Total bit width (32 or 64).
+- ``shift`` — Bit offset where this flag group starts.
+- ``range`` — Number of bits in this group.
+- ``base`` — Starting value for auto-numbering.
+- ``section`` — Documentation section.
+- ``label`` — Display label for documentation grouping.
+
+A member with a number in parentheses (e.g. ``.Z (39)``) sets an explicit bit position. Members
+with a table of names (e.g. ``.Rgb { "R", "G", "B" }``) define combined masks.
+
+struct
+~~~~~~
+
+Declares a data structure with typed fields:
+
+.. code-block:: lua
+
+    struct.Init { ctor, section = "Initialization and Shutdown" }
+        .type             "RendererType::Enum" --- Select rendering backend.
+        .vendorId         "uint16_t"           --- Vendor PCI ID. See: `BGFX_PCI_ID_*`.
+        .deviceId         "uint16_t"           --- Device ID.
+        .capabilities     "uint64_t"           --- Capabilities initialization mask.
+        .debug            "bool"               --- Enable device for debugging.
+        .profile          "bool"               --- Enable device for profiling.
+
+Attributes:
+
+- ``ctor`` — Generate a constructor with default values.
+- ``namespace`` — Nest this struct inside another (e.g. ``namespace = "Caps"`` produces
+  ``Caps::Limits``).
+- ``section`` — Documentation section.
+
+func
+~~~~
+
+Declares a function. The first string is the return type, followed by named parameters:
+
+.. code-block:: lua
+
+    --- Advance to next frame.
+    func.frame { section = "Frame" }
+        "uint32_t"                      --- Current frame number.
+        .flags "uint8_t"                --- Frame flags.
+         { default = "BGFX_FRAME_NONE" }
+
+Attributes:
+
+- ``section`` — Documentation section.
+- ``const`` — Mark as a const method (for class member functions).
+- ``conly`` — Only emit in the C99 API, not in C++.
+- ``cpponly`` — Only emit in the C++ API, not in C99.
+- ``cppinline`` — Provide an inline C++ implementation string.
+
+Parameters can have:
+
+- ``{ default = "value" }`` — Default argument value.
+- ``{ out }`` — Output parameter.
+- ``{ inout }`` — Input/output parameter.
+
+funcptr
+~~~~~~~
+
+Declares a function pointer type:
+
+.. code-block:: lua
+
+    funcptr.ReleaseFn
+        "void"
+        .ptr      "void*" --- Pointer to allocated data.
+        .userData "void*" --- User defined data if needed.
+
+section
+~~~~~~~
+
+Declares a documentation section for organizing the generated API reference. Sections form a
+hierarchy based on their level (0 = top-level heading, 1 = chapter, 2+ = subsections):
+
+.. code-block:: lua
+
+    section("API Reference", 0)
+    section("General", 1)
+    section("Initialization and Shutdown", 2)
+
+Types and functions reference their section via the ``section`` attribute. The documentation
+generator (``docs-rst.lua``) uses the section tree to organize the output.
+
+Documentation comments
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Lines starting with ``---`` before a declaration become documentation comments. These are emitted
+as Doxygen-style comments in the C/C++ headers and as descriptions in the generated docs:
+
+.. code-block:: lua
+
+    --- Render frame.
+    ---
+    --- @attention `bgfx::renderFrame` is a blocking call.
+    ---
+    --- @warning This call should only be used on platforms that don't
+    ---   allow creating a separate rendering thread.
+    ---
+    func.renderFrame { section = "Platform specific" }
+        "RenderFrame::Enum"
+        .msecs "int32_t"
+        { default = -1 }
+
+Supported Doxygen tags in comments: ``@attention``, ``@warning``, ``@remarks``, ``@param``,
+``@returns``.
+
+Adding a new API function
+--------------------------
+
+To add a new function to the bgfx API:
+
+1. Add the function declaration in ``scripts/bgfx.idl`` with the appropriate ``section`` attribute
+   and ``---`` documentation comments.
+2. Run ``make idl`` to regenerate all headers, bindings, and documentation.
+3. Implement the function in ``src/bgfx.cpp`` (and the renderer backends if needed).
+4. Verify the generated output in ``include/bgfx/bgfx.h``, ``include/bgfx/c99/bgfx.h``, and the
+   binding files under ``bindings/``.

docs/index.rst

@@ -19,4 +19,5 @@ Contents
     bgfx
     tools
     internals
+    idl
     license

docs/internals.rst

@@ -1,50 +1,289 @@
 Internals
 =========
 
-Sort based draw call bucketing
+Sort-based draw call bucketing
-------------------------------
+-------------------------------
 
-bgfx is using sort-based draw call bucketing. This means that submission order doesn't necessarily match the rendering order, but on the low-level they will be sorted and ordered correctly. On the high level bgfx uses **declarative API** and internal sorting allows more optimal way of submitting draw calls for all passes at one place, and on the low-level this allows better optimization of rendering order. This sometimes creates undesired results usually for GUI rendering, where draw order should usually match submit order. bgfx provides way to enable sequential rendering for these cases (see ``bgfx::setViewMode``).
+bgfx uses sort-based draw call bucketing. This means that the order in which draw calls are submitted does not necessarily match the order in which they are rendered. Instead, draw calls are assigned a 64-bit **sort key** and sorted before execution on the render thread, enabling more optimal GPU state management and batching.
 
- - More detailed description of sort-based draw call bucketing can be found at: `Order your graphics draw calls around! <http://realtimecollisiondetection.net/blog/?p=86>`__
+On the high level bgfx uses a **declarative API**: the user declares views, their render targets, clear parameters, and transforms up front, then submits draw calls in any order. Internally, the sort key ensures that draw calls are grouped by view first, then ordered within each view according to the active **view mode** (see ``bgfx::setViewMode``):
 
-API and render thread
+- **Default** - Sort by program first, then by depth. This groups draw calls with the same shader program together to minimise state changes, using depth as a secondary key.
----------------------
+- **Sequential** - Preserve submission order. Draw calls are rendered in exactly the order ``submit`` was called. Useful for UI/GUI rendering where painter's-order matters.
+- **DepthAscending** - Sort by depth (front-to-back). Helps maximise early-Z rejection for opaque geometry.
+- **DepthDescending** - Sort by depth (back-to-front). Required for correct blending of transparent geometry.
 
-API thread is thread from which ``bgfx::init`` is called. Once ``bgfx::init`` is called on thread, internally bgfx assumes that all API calls will be called from the same thread with exception of Resource, View, and Encoder API.
+Sort key layout
+~~~~~~~~~~~~~~~
 
-Render thread from where internal rendering ``bgfx::renderFrame`` is called. On most of OS' it's required that this call be called on thread that OS created when executing process (some refer to this thread as "main" thread, or thread where ``main`` function is called).
+Each draw call is encoded into a 64-bit sort key. The highest bits encode the **view ID**, so draw calls are always grouped by view first. Below the view bits, a **draw bit** distinguishes draw calls from compute dispatches. For draw calls, a **draw type** field selects one of three encodings to implement the view modes above:
 
-When bgfx is compiled with option ``BGFX_CONFIG_MULTITHREADED=1`` (default is on) ``bgfx::renderFrame`` can be called by user. It's required to be called before ``bgfx::init`` from thread that will be used as render thread. If both ``bgfx::renderFrame`` and ``bgfx::init`` are called from the same thread, bgfx will switch to execute in single threaded mode, and calling ``bgfx::renderFrame`` is not required, since it will be called automatically during ``bgfx::frame`` call.
+- **Program sort** (Default mode): ``[view | draw | type=0 | blend | alphaRef | program | depth]``
+- **Depth sort** (DepthAscending/DepthDescending): ``[view | draw | type=1 | depth | blend | alphaRef | program]``
+- **Sequence sort** (Sequential mode): ``[view | draw | type=2 | sequence | blend | alphaRef | program]``
+
+Compute dispatches always use sequential ordering: ``[view | compute | sequence | program]``.
+
+Sort keys are sorted via radix sort on the render thread just before GPU submission.
+
+- More detailed description of sort-based draw call bucketing can be found at: `Order your graphics draw calls around! <http://realtimecollisiondetection.net/blog/?p=86>`__
+
+API thread and render thread
+-----------------------------
+
+bgfx separates work into two threads: the **API thread** and the **render thread**.
+
+API thread
+~~~~~~~~~~
+
+The API thread is the thread from which ``bgfx::init`` is called. Once ``bgfx::init`` has been called, bgfx internally assumes that all subsequent API calls will be made from this same thread, with the exception of the Resource API, View API, and Encoder API (see sections below).
+
+The API thread is where application logic runs: setting up views, submitting draw calls via encoders, and calling ``bgfx::frame`` to advance to the next frame.
+
+Render thread
+~~~~~~~~~~~~~
+
+The render thread is where ``bgfx::renderFrame`` executes. This is the thread that talks to the GPU: it processes the command buffer, sorts draw calls, submits them to the graphics API, and performs the back-buffer flip.
+
+On most operating systems, certain graphics APIs require that rendering happens on the "main" thread (the thread on which the process was started, i.e. the thread that called ``main``). When using bgfx in multithreaded mode, the render thread is typically the main thread, while the API thread runs on a user-created secondary thread.
+
+Double-buffered frame pipeline
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+bgfx maintains two ``Frame`` objects internally: the **submit buffer** (written by the API thread) and the **render buffer** (read by the render thread). This double buffering allows the API thread and the render thread to run in parallel:
+
+1. **API thread** builds a frame by recording draw calls, state changes, and resource commands into the submit buffer.
+2. When the API thread calls ``bgfx::frame``, it waits for the render thread to finish the previous frame, then swaps the submit and render buffers (via ``bx::swap``) and signals the render thread to begin.
+3. **Render thread** (in ``bgfx::renderFrame``) wakes up, executes pre-render commands (resource creation/updates), sorts draw calls by sort key via radix sort, submits them to the GPU, executes post-render commands, flips the back buffer, and then signals back to the API thread.
+4. The API thread is now free to start building the next frame while the render thread is still executing GPU commands.
+
+The synchronisation between the two threads uses a pair of semaphores:
+
+- ``apiSemPost`` / ``apiSemWait`` - the API thread signals the render thread that a new frame is ready to process.
+- ``renderSemPost`` / ``renderSemWait`` - the render thread signals the API thread that it has finished processing.
+
+Multithreaded mode
+~~~~~~~~~~~~~~~~~~
+
+When bgfx is compiled with ``BGFX_CONFIG_MULTITHREADED=1`` (the default on all platforms that support threading), the user can call ``bgfx::renderFrame`` directly. Calling ``bgfx::renderFrame`` before ``bgfx::init`` from the intended render thread prevents bgfx from creating its own internal render thread - the user takes responsibility for calling ``bgfx::renderFrame`` externally each frame.
+
+If both ``bgfx::renderFrame`` and ``bgfx::init`` are called from the same thread, bgfx detects this and switches to **single-threaded mode**: ``bgfx::frame`` will internally invoke ``bgfx::renderFrame`` automatically, and the user does not need to call it separately.
+
+Single-threaded mode
+~~~~~~~~~~~~~~~~~~~~
+
+When compiled with ``BGFX_CONFIG_MULTITHREADED=0``, or when single-threaded mode is detected at runtime, there is no separate render thread. The call to ``bgfx::frame`` swaps buffers and immediately performs rendering inline (calls ``bgfx::renderFrame`` internally). The double-buffer swap still happens, but both sides execute on the same thread sequentially.
 
 Resource API
 ------------
 
-Any API call starting with ``bgfx::create*``, ``bgfx::destroy*``, ``bgfx::update*``, ``bgfx::alloc*`` is considered part of resource API. Internally resource API calls are guarded by mutex. There is no limit of number of threads that can call resource API simultaneously. Calling any resource API is infrequent, and functions are cheap since most of work with resource is done at later point on render thread.
+Any API call starting with ``bgfx::create*``, ``bgfx::destroy*``, ``bgfx::update*``, or ``bgfx::alloc*`` is considered part of the Resource API. Internally, Resource API calls are guarded by a mutex (``m_resourceApiLock``), so there is no limit on the number of threads that can call Resource API functions simultaneously.
+
+Calling any Resource API function is generally infrequent and cheap on the API thread side, because the actual GPU work (uploading textures, creating buffers, etc.) is deferred: the commands are recorded into the frame's command buffer and executed later on the render thread via ``rendererExecCommands``.
+
+Resource handles (``TextureHandle``, ``VertexBufferHandle``, etc.) are returned immediately on creation and can be used in draw calls right away, even though the GPU resource may not yet exist. The render thread will process the creation command before it processes any draw calls that reference the handle.
 
 View API
 --------
 
-Any API call starting with ``bgfx::setView*`` is considered part of view API. View API is not designed to be thread safe at all since all views are independentent from each other. Calling any view API for different views from different threads is safe. What's not safe is to update the same view from multiple threads. This will lead to undefined behavior. Only view API that has to be set before any draw calls are issued is view mode ``bgfx::setViewMode``. Internal encoder requires view mode to select sort key encoding and if user changes view mode after submit it will cause incorrect sort behavior within the view.
+Any API call starting with ``bgfx::setView*`` is considered part of the View API. The View API is **not** internally thread safe - but it doesn't need to be, because views are independent from each other. Calling any view API for different views from different threads is safe. What is **not** safe is updating the same view from multiple threads simultaneously; doing so leads to undefined behaviour.
+
+One important constraint: ``bgfx::setViewMode`` must be set **before** any draw calls are submitted to that view within a frame. The internal encoder reads the view mode at submit time to select the sort key encoding. Changing the view mode after draw calls have already been submitted to that view will cause incorrect sort behaviour.
+
+The maximum number of views is configured by ``BGFX_CONFIG_MAX_VIEWS`` (default: 256, must be a power of 2). Views are referenced by ``ViewId`` (a 16-bit integer).
 
 Encoder API
 -----------
 
-Encoder API can be obtained by calling ``bgfx::begin``. bgfx by default allows 8 simultaneous threads to use encoders. This can be configured by changing ``Limits.maxEncoders`` init option of ``bgfx::Init`` structure.
+The Encoder API is used for submitting draw calls and dispatches from multiple threads. An encoder is obtained by calling ``bgfx::begin`` and returned with ``bgfx::end``.
+
+By default, bgfx allows up to **8 simultaneous encoders** (configurable via ``Limits.maxEncoders`` in ``bgfx::Init``). Each encoder writes into its own ``UniformBuffer``, so there is no contention between threads when recording draw calls.
+
+When ``bgfx::frame`` is called, it waits for all active encoders to finish (``encoderApiWait``), then locks the encoder mutex to prevent new encoders from being created. The submit buffer is then finalized and swapped.
+
+Encoder 0 is special: it is the "default encoder" used by the legacy non-encoder API (``bgfx::setState``, ``bgfx::submit``, etc.) and is always allocated internally. The remaining encoder slots are available for user-created encoders for multithreaded submission.
+
+Transient buffers
+-----------------
+
+Transient vertex and index buffers are per-frame temporary allocations intended for dynamic geometry that changes every frame (e.g. debug rendering, particles, UI). They are allocated from a ring buffer that is reset each frame.
+
+Each of the two ``Frame`` objects owns its own transient vertex buffer and transient index buffer. When the frame buffers are swapped, the new submit buffer gets a fresh transient allocation. This means that pointers obtained from ``bgfx::allocTransientVertexBuffer`` / ``bgfx::allocTransientIndexBuffer`` are only valid until the next call to ``bgfx::frame``.
+
+The maximum size of transient buffers can be configured via ``Limits.maxTransientVbSize`` and ``Limits.maxTransientIbSize`` in ``bgfx::Init``.
 
 Customization
 -------------
 
-By default each platform has sane default values. For example on Windows default renderer is DirectX, on Linux it is OpenGL, and on macOS it's Metal. On Windows platform almost all rendering backends are available. For OpenGL ES on desktop you can find more information at:- `OpenGL ES 2.0 and EGL on desktop <http://www.g-truc.net/post-0457.html>`__
+By default each platform has sane default values. For example on Windows the default renderer is Direct3D 12, on Linux it is Vulkan, and on macOS it's Metal. On Windows, almost all rendering backends are available. For OpenGL ES on desktop you can find more information at: `OpenGL ES 2.0 and EGL on desktop <http://www.g-truc.net/post-0457.html>`__
 
-If you're targeting specific mobile hardware, you can find GLES support in their official SDKs: `Adreno
+If you're targeting specific mobile hardware, you can find GLES support in their official SDKs: `Adreno SDK <http://developer.qualcomm.com/mobile-development/mobile-technologies/gaming-graphics-optimization-adreno/tools-and-resources>`__, `Mali SDK <http://www.malideveloper.com/>`__, `PowerVR SDK <http://www.imgtec.com/powervr/insider/sdkdownloads/>`__.
-SDK <http://developer.qualcomm.com/mobile-development/mobile-technologies/gaming-graphics-optimization-adreno/tools-and-resources>`__, `Mali SDK <http://www.malideveloper.com/>`__, `PowerVR SDK <http://www.imgtec.com/powervr/insider/sdkdownloads/>`__.
 
 All configuration settings are located inside `src/config.h <https://github.com/bkaradzic/bgfx/blob/master/src/config.h>`__.
 
-Every ``BGFX_CONFIG_*`` setting can be changed by passing defines thru compiler switches. For example setting preprocessor define ``BGFX_CONFIG_RENDERER_OPENGL=1`` will change backend renderer to OpenGL 2.1. on Windows. Since rendering APIs are platform specific, this obviously won't work nor make sense in all cases.
+Every ``BGFX_CONFIG_*`` setting can be changed by passing defines through compiler switches. For example setting preprocessor define ``BGFX_CONFIG_RENDERER_OPENGL=1`` will change the backend renderer to OpenGL 2.1 on Windows. Since rendering APIs are platform specific, this obviously won't work nor make sense in all cases.
 
 Options
 ~~~~~~~
 
-``BGFX_CONFIG_MULTITHREADED`` is used to enable/disable threading support inside bgfx. By default set to 1 on all platforms that support threading.
+Threading and synchronisation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``BGFX_CONFIG_MULTITHREADED`` - Enable/disable multithreaded rendering. When enabled, bgfx can use a separate render thread for GPU submission. Default is 1 on all platforms that support threading (0 on Emscripten).
+
+``BGFX_CONFIG_API_SEMAPHORE_TIMEOUT`` - Timeout in milliseconds for the API/render thread semaphore wait. Default is 5000 ms. If the semaphore times out, it typically indicates a deadlock or the other thread has stalled.
+
+``BGFX_CONFIG_DEFAULT_MAX_ENCODERS`` - Default maximum number of simultaneous encoders for multithreaded draw call submission. Default is 8 when multithreaded, 1 otherwise. Can be overridden at runtime via ``Limits.maxEncoders`` in ``bgfx::Init``.
+
+``BGFX_CONFIG_ENCODER_API_ONLY`` - When set to 1, disable the legacy non-encoder API (``bgfx::setState``, ``bgfx::submit``, etc.) and require all submissions to go through the Encoder API (``bgfx::begin`` / ``bgfx::end``). Default is 0.
+
+Renderer backends
+^^^^^^^^^^^^^^^^^
+
+``BGFX_CONFIG_RENDERER_AGC`` - Enable AGC renderer backend (PS5). Default is auto-detected per platform.
+
+``BGFX_CONFIG_RENDERER_DIRECT3D11`` - Enable Direct3D 11 renderer backend. Default is 1 on Windows/Linux.
+
+``BGFX_CONFIG_RENDERER_DIRECT3D12`` - Enable Direct3D 12 renderer backend. Default is 1 on Windows/Linux.
+
+``BGFX_CONFIG_RENDERER_GNM`` - Enable GNM renderer backend (PS4). Default is auto-detected per platform.
+
+``BGFX_CONFIG_RENDERER_METAL`` - Enable Metal renderer backend. Default is 1 on iOS/macOS/visionOS.
+
+``BGFX_CONFIG_RENDERER_NVN`` - Enable NVN renderer backend (Nintendo Switch). Default is auto-detected per platform.
+
+``BGFX_CONFIG_RENDERER_OPENGL`` - Enable OpenGL renderer backend. Set to the minimum GL version (e.g. 21 for OpenGL 2.1, 33 for 3.3, 44 for 4.4). Default is auto-detected per platform; minimum is 21 if enabled.
+
+``BGFX_CONFIG_RENDERER_OPENGLES`` - Enable OpenGL ES renderer backend. Set to the minimum GLES version (e.g. 20 for ES 2.0, 30 for ES 3.0). Default is auto-detected per platform; minimum is 20 if enabled. Cannot be combined with ``BGFX_CONFIG_RENDERER_OPENGL``.
+
+``BGFX_CONFIG_RENDERER_VULKAN`` - Enable Vulkan renderer backend. Default is 1 on Android/Linux/Windows/macOS/NX.
+
+``BGFX_CONFIG_RENDERER_WEBGPU`` - Enable WebGPU renderer backend. Default is 1 on Linux/macOS/Windows.
+
+``BGFX_CONFIG_RENDERER_USE_EXTENSIONS`` - Enable use of renderer-specific API extensions (e.g. OpenGL extensions, Vulkan extensions). Default is 1.
+
+``BGFX_CONFIG_RENDERER_DIRECT3D11_USE_STAGING_BUFFER`` - Enable use of staging buffers in the Direct3D 11 renderer for texture and buffer updates. Default is 0.
+
+``BGFX_CONFIG_RENDERER_VULKAN_MAX_DESCRIPTOR_SETS_PER_FRAME`` - Maximum number of Vulkan descriptor sets allocated per frame. Default is 1024. Each draw/compute call may consume one descriptor set.
+
+Resource limits
+^^^^^^^^^^^^^^^
+
+``BGFX_CONFIG_MAX_DRAW_CALLS`` - Maximum number of draw/compute calls per frame. Default is 65535 (64K - 1).
+
+``BGFX_CONFIG_MAX_BLIT_ITEMS`` - Maximum number of blit items per frame. Default is 1024.
+
+``BGFX_CONFIG_MAX_VIEWS`` - Maximum number of views. Default is 256. Must be a power of 2.
+
+``BGFX_CONFIG_MAX_VIEW_NAME`` - Maximum length of a view name string. Default is 256.
+
+``BGFX_CONFIG_MAX_VERTEX_LAYOUTS`` - Maximum number of vertex layout declarations. Default is 64.
+
+``BGFX_CONFIG_MAX_INDEX_BUFFERS`` - Maximum number of static index buffer handles. Default is 4096.
+
+``BGFX_CONFIG_MAX_VERTEX_BUFFERS`` - Maximum number of static vertex buffer handles. Default is 4096.
+
+``BGFX_CONFIG_MAX_VERTEX_STREAMS`` - Maximum number of vertex streams per draw call. Default is 4.
+
+``BGFX_CONFIG_MAX_DYNAMIC_INDEX_BUFFERS`` - Maximum number of dynamic index buffer handles. Default is 4096.
+
+``BGFX_CONFIG_MAX_DYNAMIC_VERTEX_BUFFERS`` - Maximum number of dynamic vertex buffer handles. Default is 4096.
+
+``BGFX_CONFIG_MAX_SHADERS`` - Maximum number of shader handles (vertex + fragment + compute). Default is 512.
+
+``BGFX_CONFIG_MAX_TEXTURES`` - Maximum number of texture handles. Default is 4096.
+
+``BGFX_CONFIG_MAX_TEXTURE_SAMPLERS`` - Maximum number of texture samplers per draw call. Default is 16.
+
+``BGFX_CONFIG_MAX_FRAME_BUFFERS`` - Maximum number of frame buffer handles. Default is 128.
+
+``BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS`` - Maximum number of attachments (color + depth/stencil) per frame buffer. Default is 8.
+
+``BGFX_CONFIG_MAX_UNIFORMS`` - Maximum number of uniform handles. Default is 512.
+
+``BGFX_CONFIG_MAX_OCCLUSION_QUERIES`` - Maximum number of occlusion query handles. Default is 256.
+
+``BGFX_CONFIG_MAX_INSTANCE_DATA_COUNT`` - Maximum number of instance data vec4 attributes per draw call. Default is 5. Total instance stride is count × 16 bytes.
+
+``BGFX_CONFIG_MAX_COLOR_PALETTE`` - Maximum number of color palette entries for indexed clear colors. Default is 16.
+
+``BGFX_CONFIG_MAX_SCREENSHOTS`` - Maximum number of screenshot requests that can be queued per frame. Default is 4.
+
+``BGFX_CONFIG_MAX_PROGRAMS`` - Maximum number of linked programs. Derived from ``2^BGFX_CONFIG_SORT_KEY_NUM_BITS_PROGRAM``. Default is 512. Cannot be configured directly.
+
+Buffer sizes
+^^^^^^^^^^^^^
+
+``BGFX_CONFIG_DYNAMIC_INDEX_BUFFER_SIZE`` - Initial size in bytes of the dynamic index buffer backing store. Default is 1 MB. The backing store grows as needed via sub-allocation.
+
+``BGFX_CONFIG_DYNAMIC_VERTEX_BUFFER_SIZE`` - Initial size in bytes of the dynamic vertex buffer backing store. Default is 3 MB. The backing store grows as needed via sub-allocation.
+
+``BGFX_CONFIG_MAX_TRANSIENT_VERTEX_BUFFER_SIZE`` - Maximum transient vertex buffer size. There is no growth; all transient vertices must fit into this buffer. Default is 6 MB.
+
+``BGFX_CONFIG_MAX_TRANSIENT_INDEX_BUFFER_SIZE`` - Maximum transient index buffer size. There is no growth; all transient indices must fit into this buffer. Default is 2 MB.
+
+``BGFX_CONFIG_MIN_RESOURCE_COMMAND_BUFFER_SIZE`` - Minimum initial size of the resource command buffer (pre/post render commands for resource creation and updates). Default is 64 KB. The buffer grows as needed.
+
+``BGFX_CONFIG_MIN_UNIFORM_BUFFER_SIZE`` - Minimum initial size in bytes of the per-encoder uniform buffer. Default is 1 MB. This buffer will resize on demand.
+
+``BGFX_CONFIG_UNIFORM_BUFFER_RESIZE_THRESHOLD_SIZE`` - Maximum amount of unused uniform buffer space (in bytes) before the buffer is shrunk. Default is 64 KB.
+
+``BGFX_CONFIG_UNIFORM_BUFFER_RESIZE_INCREMENT_SIZE`` - Increment size for uniform buffer resize. Default is 1 MB.
+
+``BGFX_CONFIG_CACHED_DEVICE_MEMORY_ALLOCATIONS_SIZE`` - Amount of allowed memory allocations left on device to use for recycling during later allocations. This can be beneficial in case the driver is slow allocating memory on the device. Default is 128 MB. Currently only used by the Vulkan backend.
+
+``BGFX_CONFIG_MAX_STAGING_SCRATCH_BUFFER_SIZE`` - Threshold of data size above which the staging scratch buffer will not be used; instead a separate device memory allocation will take place to stage the data. Default is 16 MB.
+
+``BGFX_CONFIG_MAX_SCRATCH_STAGING_BUFFER_PER_FRAME_SIZE`` - Amount of scratch buffer size (per in-flight frame) reserved for staging data for copying to the device (vertex buffers, textures, etc.). Default is 32 MB. Currently only used by the Vulkan backend.
+
+Sort key
+^^^^^^^^
+
+``BGFX_CONFIG_SORT_KEY_NUM_BITS_DEPTH`` - Number of bits used for depth in the sort key. Default is 32. Reducing this allows more bits for other sort key fields.
+
+``BGFX_CONFIG_SORT_KEY_NUM_BITS_SEQ`` - Number of bits used for sequence number in the sort key. Default is 20. Determines the maximum number of draw calls per view in sequential mode (2^20 ≈ 1M).
+
+``BGFX_CONFIG_SORT_KEY_NUM_BITS_PROGRAM`` - Number of bits used for program index in the sort key. Default is 9. Determines ``BGFX_CONFIG_MAX_PROGRAMS`` (2^9 = 512).
+
+``BGFX_CONFIG_MAX_MATRIX_CACHE`` - Maximum number of cached transform matrices per frame. Default is ``BGFX_CONFIG_MAX_DRAW_CALLS + 1``.
+
+``BGFX_CONFIG_MAX_RECT_CACHE`` - Maximum number of cached scissor rectangles per frame. Default is 4096.
+
+Swap chain
+^^^^^^^^^^
+
+``BGFX_CONFIG_MAX_BACK_BUFFERS`` - Maximum number of back buffers for the swap chain. Default is 4. The actual number used is specified via ``bgfx::Resolution::numBackBuffers``.
+
+``BGFX_CONFIG_MAX_FRAME_LATENCY`` - Maximum frame latency (number of frames that can be queued ahead). Default is 3. The actual value is specified via ``bgfx::Resolution::maxFrameLatency``.
+
+Debugging and profiling
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``BGFX_CONFIG_DEBUG_TEXT_MAX_SCALE`` - Debug text maximum scale factor for ``bgfx::dbgTextPrintf``. Default is 4.
+
+``BGFX_CONFIG_DEBUG_PERFHUD`` - Enable nVidia PerfHUD integration. Default is 0.
+
+``BGFX_CONFIG_DEBUG_ANNOTATION`` - Enable annotation for graphics debuggers (e.g. RenderDoc, PIX). Default matches ``BGFX_CONFIG_DEBUG``.
+
+``BGFX_CONFIG_DEBUG_OBJECT_NAME`` - Enable debug names on graphics API objects (Direct3D 11/12, Vulkan, etc.). Default matches ``BGFX_CONFIG_DEBUG_ANNOTATION``.
+
+``BGFX_CONFIG_DEBUG_UNIFORM`` - Enable runtime validation that uniforms are set before each draw call. Default matches ``BGFX_CONFIG_DEBUG``.
+
+``BGFX_CONFIG_DEBUG_OCCLUSION`` - Enable runtime validation that occlusion queries are not reused within the same frame. Default matches ``BGFX_CONFIG_DEBUG``.
+
+``BGFX_CONFIG_PROFILER`` - Enable internal profiler instrumentation. When enabled, bgfx will emit profiler scopes for frame, submit, resource, and view operations. Default is 0.
+
+``BGFX_CONFIG_RENDERDOC_LOG_FILEPATH`` - File path for RenderDoc capture log output. Default is ``"temp/bgfx"``.
+
+``BGFX_CONFIG_RENDERDOC_CAPTURE_KEYS`` - Key(s) to trigger a RenderDoc capture. Default is ``{ eRENDERDOC_Key_F11 }``.
+
+Miscellaneous
+^^^^^^^^^^^^^
+
+``BGFX_CONFIG_USE_TINYSTL`` - Enable use of tinystl instead of std containers for internal data structures. Default is 1. Reduces binary size and avoids std library dependency.
+
+``BGFX_CONFIG_MIP_LOD_BIAS`` - Global MIP level-of-detail bias applied to all texture sampling. Default is 0. Positive values select coarser MIP levels, negative values select finer MIP levels.
+
+``BGFX_CONFIG_DRAW_INDIRECT_STRIDE`` - Stride in bytes of each draw indirect command. Fixed at 32 bytes. Not configurable.
+
+``BGFX_CONFIG_PREFER_DISCRETE_GPU`` - On laptops with integrated and discrete GPU, prefer selection of the discrete GPU (nVidia and AMD). Default is 1 on Windows, 0 elsewhere.

include/bgfx/bgfx.h

@@ -168,106 +168,106 @@ namespace bgfx
 		/// Texture formats:
 		enum Enum
 		{
-			BC1,          //!< DXT1 R5G6B5A1
+			BC1,          //!< Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP.
-			BC2,          //!< DXT3 R5G6B5A4
+			BC2,          //!< Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP.
-			BC3,          //!< DXT5 R5G6B5A8
+			BC3,          //!< Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP.
-			BC4,          //!< LATC1/ATI1 R8
+			BC4,          //!< Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP.
-			BC5,          //!< LATC2/ATI2 RG8
+			BC5,          //!< Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP.
-			BC6H,         //!< BC6H RGB16F
+			BC6H,         //!< Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP.
-			BC7,          //!< BC7 RGB 4-7 bits per color channel, 0-8 bits alpha
+			BC7,          //!< RGB 4-7 bits per color channel, 0-8 bits alpha. Block Compression 7. High-quality RGBA, 4-7 bits per color, 0-8 bits alpha. 8 BPP.
-			ETC1,         //!< ETC1 RGB8
+			ETC1,         //!< Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP.
-			ETC2,         //!< ETC2 RGB8
+			ETC2,         //!< Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP.
-			ETC2A,        //!< ETC2 RGBA8
+			ETC2A,        //!< Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP.
-			ETC2A1,       //!< ETC2 RGB8A1
+			ETC2A1,       //!< Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP.
-			EACR11,       //!< EAC R11 UNORM
+			EACR11,       //!< ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP.
-			EACR11S,      //!< EAC R11 SNORM
+			EACR11S,      //!< ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP.
-			EACRG11,      //!< EAC RG11 UNORM
+			EACRG11,      //!< ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP.
-			EACRG11S,     //!< EAC RG11 SNORM
+			EACRG11S,     //!< ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP.
-			PTC12,        //!< PVRTC1 RGB 2BPP
+			PTC12,        //!< PowerVR Texture Compression v1. 3-channel RGB. 2 BPP.
-			PTC14,        //!< PVRTC1 RGB 4BPP
+			PTC14,        //!< PowerVR Texture Compression v1. 3-channel RGB. 4 BPP.
-			PTC12A,       //!< PVRTC1 RGBA 2BPP
+			PTC12A,       //!< PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP.
-			PTC14A,       //!< PVRTC1 RGBA 4BPP
+			PTC14A,       //!< PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP.
-			PTC22,        //!< PVRTC2 RGBA 2BPP
+			PTC22,        //!< PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP.
-			PTC24,        //!< PVRTC2 RGBA 4BPP
+			PTC24,        //!< PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP.
-			ATC,          //!< ATC RGB 4BPP
+			ATC,          //!< AMD Texture Compression. 3-channel RGB. 4 BPP.
-			ATCE,         //!< ATCE RGBA 8 BPP explicit alpha
+			ATCE,         //!< AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP.
-			ATCI,         //!< ATCI RGBA 8 BPP interpolated alpha
+			ATCI,         //!< AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP.
-			ASTC4x4,      //!< ASTC 4x4 8.0 BPP
+			ASTC4x4,      //!< Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP.
-			ASTC5x4,      //!< ASTC 5x4 6.40 BPP
+			ASTC5x4,      //!< Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP.
-			ASTC5x5,      //!< ASTC 5x5 5.12 BPP
+			ASTC5x5,      //!< Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP.
-			ASTC6x5,      //!< ASTC 6x5 4.27 BPP
+			ASTC6x5,      //!< Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP.
-			ASTC6x6,      //!< ASTC 6x6 3.56 BPP
+			ASTC6x6,      //!< Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP.
-			ASTC8x5,      //!< ASTC 8x5 3.20 BPP
+			ASTC8x5,      //!< Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP.
-			ASTC8x6,      //!< ASTC 8x6 2.67 BPP
+			ASTC8x6,      //!< Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP.
-			ASTC8x8,      //!< ASTC 8x8 2.00 BPP
+			ASTC8x8,      //!< Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP.
-			ASTC10x5,     //!< ASTC 10x5 2.56 BPP
+			ASTC10x5,     //!< Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP.
-			ASTC10x6,     //!< ASTC 10x6 2.13 BPP
+			ASTC10x6,     //!< Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP.
-			ASTC10x8,     //!< ASTC 10x8 1.60 BPP
+			ASTC10x8,     //!< Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP.
-			ASTC10x10,    //!< ASTC 10x10 1.28 BPP
+			ASTC10x10,    //!< Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP.
-			ASTC12x10,    //!< ASTC 12x10 1.07 BPP
+			ASTC12x10,    //!< Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP.
-			ASTC12x12,    //!< ASTC 12x12 0.89 BPP
+			ASTC12x12,    //!< Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP.
 			Unknown,      //!< Compressed formats above.
-			R1,
+			R1,           //!< 1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP.
-			A8,
+			A8,           //!< 8-bit single-channel alpha, unsigned normalized. 8 BPP.
-			R8,
+			R8,           //!< 8-bit single-channel red, unsigned normalized. 8 BPP.
-			R8I,
+			R8I,          //!< 8-bit single-channel red, signed integer. 8 BPP.
-			R8U,
+			R8U,          //!< 8-bit single-channel red, unsigned integer. 8 BPP.
-			R8S,
+			R8S,          //!< 8-bit single-channel red, signed normalized. 8 BPP.
-			R16,
+			R16,          //!< 16-bit single-channel red, unsigned normalized. 16 BPP.
-			R16I,
+			R16I,         //!< 16-bit single-channel red, signed integer. 16 BPP.
-			R16U,
+			R16U,         //!< 16-bit single-channel red, unsigned integer. 16 BPP.
-			R16F,
+			R16F,         //!< 16-bit single-channel red, half-precision floating point. 16 BPP.
-			R16S,
+			R16S,         //!< 16-bit single-channel red, signed normalized. 16 BPP.
-			R32I,
+			R32I,         //!< 32-bit single-channel red, signed integer. 32 BPP.
-			R32U,
+			R32U,         //!< 32-bit single-channel red, unsigned integer. 32 BPP.
-			R32F,
+			R32F,         //!< 32-bit single-channel red, full-precision floating point. 32 BPP.
-			RG8,
+			RG8,          //!< Two 8-bit channels (red, green), unsigned normalized. 16 BPP.
-			RG8I,
+			RG8I,         //!< Two 8-bit channels (red, green), signed integer. 16 BPP.
-			RG8U,
+			RG8U,         //!< Two 8-bit channels (red, green), unsigned integer. 16 BPP.
-			RG8S,
+			RG8S,         //!< Two 8-bit channels (red, green), signed normalized. 16 BPP.
-			RG16,
+			RG16,         //!< Two 16-bit channels (red, green), unsigned normalized. 32 BPP.
-			RG16I,
+			RG16I,        //!< Two 16-bit channels (red, green), signed integer. 32 BPP.
-			RG16U,
+			RG16U,        //!< Two 16-bit channels (red, green), unsigned integer. 32 BPP.
-			RG16F,
+			RG16F,        //!< Two 16-bit channels (red, green), half-precision floating point. 32 BPP.
-			RG16S,
+			RG16S,        //!< Two 16-bit channels (red, green), signed normalized. 32 BPP.
-			RG32I,
+			RG32I,        //!< Two 32-bit channels (red, green), signed integer. 64 BPP.
-			RG32U,
+			RG32U,        //!< Two 32-bit channels (red, green), unsigned integer. 64 BPP.
-			RG32F,
+			RG32F,        //!< Two 32-bit channels (red, green), full-precision floating point. 64 BPP.
-			RGB8,
+			RGB8,         //!< Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP.
-			RGB8I,
+			RGB8I,        //!< Three 8-bit channels (red, green, blue), signed integer. 24 BPP.
-			RGB8U,
+			RGB8U,        //!< Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP.
-			RGB8S,
+			RGB8S,        //!< Three 8-bit channels (red, green, blue), signed normalized. 24 BPP.
-			RGB9E5F,
+			RGB9E5F,      //!< Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP.
-			BGRA8,
+			BGRA8,        //!< Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP.
-			RGBA8,
+			RGBA8,        //!< Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP.
-			RGBA8I,
+			RGBA8I,       //!< Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP.
-			RGBA8U,
+			RGBA8U,       //!< Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP.
-			RGBA8S,
+			RGBA8S,       //!< Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP.
-			RGBA16,
+			RGBA16,       //!< Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP.
-			RGBA16I,
+			RGBA16I,      //!< Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP.
-			RGBA16U,
+			RGBA16U,      //!< Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP.
-			RGBA16F,
+			RGBA16F,      //!< Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP.
-			RGBA16S,
+			RGBA16S,      //!< Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP.
-			RGBA32I,
+			RGBA32I,      //!< Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP.
-			RGBA32U,
+			RGBA32U,      //!< Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP.
-			RGBA32F,
+			RGBA32F,      //!< Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP.
-			B5G6R5,
+			B5G6R5,       //!< Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP.
-			R5G6B5,
+			R5G6B5,       //!< Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP.
-			BGRA4,
+			BGRA4,        //!< Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP.
-			RGBA4,
+			RGBA4,        //!< Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP.
-			BGR5A1,
+			BGR5A1,       //!< Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP.
-			RGB5A1,
+			RGB5A1,       //!< Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP.
-			RGB10A2,
+			RGB10A2,      //!< Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP.
-			RG11B10F,
+			RG11B10F,     //!< Packed 32-bit, 11-bit red, 11-bit green, 10-bit blue, unsigned floating point. No alpha. 32 BPP.
 			UnknownDepth, //!< Depth formats below.
-			D16,
+			D16,          //!< 16-bit depth, unsigned normalized. 16 BPP.
-			D24,
+			D24,          //!< 24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP.
-			D24S8,
+			D24S8,        //!< 24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP.
-			D32,
+			D32,          //!< 32-bit depth, unsigned normalized. 32 BPP.
-			D16F,
+			D16F,         //!< 16-bit depth, floating point. 16 BPP.
-			D24F,
+			D24F,         //!< 24-bit depth, floating point (stored as 32-bit). 32 BPP.
-			D32F,
+			D32F,         //!< 32-bit depth, floating point. 32 BPP.
-			D0S8,
+			D0S8,         //!< 8-bit stencil only, no depth. 8 BPP.
 
 			Count
 		};
@@ -2136,9 +2136,21 @@ namespace bgfx
 		, TextureFormat::Enum _format = TextureFormat::Count
 		);
 
-	/// Advance to next frame. When using multithreaded renderer, this call
+	/// Advance to next frame. This is the main frame-advancement call on the
-	/// just swaps internal buffers, kicks render thread, and returns. In
+	/// API thread (the thread from which `bgfx::init` was called).
-	/// singlethreaded renderer this call does frame rendering.
+	///
+	/// **Multithreaded renderer** (`BGFX_CONFIG_MULTITHREADED=1`, default):
+	/// This call waits for the render thread to finish processing the previous
+	/// frame, then swaps internal submit/render buffers, signals the render
+	/// thread to begin processing the new frame via `bgfx::renderFrame`, and
+	/// returns immediately. The render thread and API thread then run in
+	/// parallel: the API thread builds the next frame while the render thread
+	/// executes GPU commands for the current frame.
+	///
+	/// **Single-threaded renderer** (`BGFX_CONFIG_MULTITHREADED=0`, or when
+	/// `bgfx::renderFrame` and `bgfx::init` are called from the same thread):
+	/// This call swaps internal buffers and performs frame rendering inline
+	/// (internally calls `bgfx::renderFrame`), then returns.
 	///
 	/// @param[in] _flags Frame flags. See: `BGFX_FRAME_*` for more info.
 	///   - `BGFX_FRAME_NONE` - No frame flag.
@@ -2149,6 +2161,14 @@ namespace bgfx
 	///   double/multi buffering data outside the library and passing it to
 	///   library via `bgfx::makeRef` calls.
 	///
+	/// @remarks
+	///   Must be called from the API thread (the thread that called
+	///   `bgfx::init`). In multithreaded mode, this call synchronizes with
+	///   `bgfx::renderFrame` running on the render thread via semaphores:
+	///   `bgfx::frame` waits for the render thread to finish, then posts a
+	///   signal that `bgfx::renderFrame` waits on to begin the next frame.
+	///   See also: `bgfx::renderFrame`.
+	///
 	/// @attention C99's equivalent binding is `bgfx_frame`.
 	///
 	uint32_t frame(uint8_t _flags = BGFX_FRAME_NONE);
@@ -3787,20 +3807,47 @@ namespace bgfx
 		, const char* _filePath
 		);
 
-	/// Render frame.
+	/// Render frame. Executes the actual GPU rendering work for one frame.
+	///
+	/// In the default **multithreaded** configuration, `bgfx::renderFrame` runs
+	/// on the **render thread** while `bgfx::frame` runs on the **API thread**.
+	/// Their interaction is as follows:
+	///
+	///   1. The render thread calls `bgfx::renderFrame`, which blocks waiting
+	///      for the API thread to signal that a new frame is ready.
+	///   2. On the API thread, `bgfx::frame` finishes building the frame,
+	///      swaps internal submit/render buffers, and signals the render thread.
+	///   3. `bgfx::renderFrame` wakes up, executes pre-render commands,
+	///      submits GPU draw calls, executes post-render commands, flips the
+	///      back buffer, then signals back to the API thread that rendering
+	///      is complete.
+	///   4. The API thread's next `bgfx::frame` call waits for this completion
+	///      signal before swapping buffers again.
+	///
+	/// This double-buffered semaphore handshake allows the API thread and
+	/// render thread to run in parallel, overlapping CPU frame building with
+	/// GPU rendering.
 	///
 	/// @param[in] _msecs Timeout in milliseconds.
 	///
 	/// @returns Current renderer context state. See: `bgfx::RenderFrame`.
 	///
-	/// @attention `bgfx::renderFrame` is blocking call. It waits for
+	/// @attention `bgfx::renderFrame` is a blocking call. It waits for
-	///   `bgfx::frame` to be called from API thread to process frame.
+	///   `bgfx::frame` to be called from the API thread to process the frame.
-	///   If timeout value is passed call will timeout and return even
+	///   If a timeout value is passed, the call will return
-	///   if `bgfx::frame` is not called.
+	///   `RenderFrame::Timeout` even if `bgfx::frame` has not been called.
+	///   A value of -1 (default) means wait indefinitely (up to
+	///   `BGFX_CONFIG_API_SEMAPHORE_TIMEOUT`).
 	///
-	/// @warning This call should be only used on platforms that don't
+	/// @warning This call should only be used on platforms that don't allow
-	///   allow creating separate rendering thread. If it is called before
+	///   creating a separate rendering thread. If it is called before
-	///   to bgfx::init, render thread won't be created by bgfx::init call.
+	///   `bgfx::init`, the internal render thread won't be created by the
+	///   `bgfx::init` call, and the user is responsible for calling
+	///   `bgfx::renderFrame` on the render thread each frame. If both
+	///   `bgfx::renderFrame` and `bgfx::init` are called from the same
+	///   thread, bgfx operates in single-threaded mode and `bgfx::frame`
+	///   will internally invoke `bgfx::renderFrame` automatically.
+	///   See also: `bgfx::frame`.
 	///
 	/// @attention C99's equivalent binding is `bgfx_render_frame`.
 	///

include/bgfx/c99/bgfx.h

@@ -175,106 +175,106 @@ typedef enum bgfx_attrib_type
  */
 typedef enum bgfx_texture_format
 {
-    BGFX_TEXTURE_FORMAT_BC1,                  /** ( 0) DXT1 R5G6B5A1                  */
+    BGFX_TEXTURE_FORMAT_BC1,                  /** ( 0) Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_BC2,                  /** ( 1) DXT3 R5G6B5A4                  */
+    BGFX_TEXTURE_FORMAT_BC2,                  /** ( 1) Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_BC3,                  /** ( 2) DXT5 R5G6B5A8                  */
+    BGFX_TEXTURE_FORMAT_BC3,                  /** ( 2) Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_BC4,                  /** ( 3) LATC1/ATI1 R8                  */
+    BGFX_TEXTURE_FORMAT_BC4,                  /** ( 3) Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_BC5,                  /** ( 4) LATC2/ATI2 RG8                 */
+    BGFX_TEXTURE_FORMAT_BC5,                  /** ( 4) Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_BC6H,                 /** ( 5) BC6H RGB16F                    */
+    BGFX_TEXTURE_FORMAT_BC6H,                 /** ( 5) Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_BC7,                  /** ( 6) BC7 RGB 4-7 bits per color channel, 0-8 bits alpha */
+    BGFX_TEXTURE_FORMAT_BC7,                  /** ( 6) RGB 4-7 bits per color channel, 0-8 bits alpha. Block Compression 7. High-quality RGBA, 4-7 bits per color, 0-8 bits alpha. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_ETC1,                 /** ( 7) ETC1 RGB8                      */
+    BGFX_TEXTURE_FORMAT_ETC1,                 /** ( 7) Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_ETC2,                 /** ( 8) ETC2 RGB8                      */
+    BGFX_TEXTURE_FORMAT_ETC2,                 /** ( 8) Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_ETC2A,                /** ( 9) ETC2 RGBA8                     */
+    BGFX_TEXTURE_FORMAT_ETC2A,                /** ( 9) Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_ETC2A1,               /** (10) ETC2 RGB8A1                    */
+    BGFX_TEXTURE_FORMAT_ETC2A1,               /** (10) Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_EACR11,               /** (11) EAC R11 UNORM                  */
+    BGFX_TEXTURE_FORMAT_EACR11,               /** (11) ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_EACR11S,              /** (12) EAC R11 SNORM                  */
+    BGFX_TEXTURE_FORMAT_EACR11S,              /** (12) ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_EACRG11,              /** (13) EAC RG11 UNORM                 */
+    BGFX_TEXTURE_FORMAT_EACRG11,              /** (13) ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_EACRG11S,             /** (14) EAC RG11 SNORM                 */
+    BGFX_TEXTURE_FORMAT_EACRG11S,             /** (14) ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_PTC12,                /** (15) PVRTC1 RGB 2BPP                */
+    BGFX_TEXTURE_FORMAT_PTC12,                /** (15) PowerVR Texture Compression v1. 3-channel RGB. 2 BPP. */
-    BGFX_TEXTURE_FORMAT_PTC14,                /** (16) PVRTC1 RGB 4BPP                */
+    BGFX_TEXTURE_FORMAT_PTC14,                /** (16) PowerVR Texture Compression v1. 3-channel RGB. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_PTC12A,               /** (17) PVRTC1 RGBA 2BPP               */
+    BGFX_TEXTURE_FORMAT_PTC12A,               /** (17) PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP. */
-    BGFX_TEXTURE_FORMAT_PTC14A,               /** (18) PVRTC1 RGBA 4BPP               */
+    BGFX_TEXTURE_FORMAT_PTC14A,               /** (18) PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_PTC22,                /** (19) PVRTC2 RGBA 2BPP               */
+    BGFX_TEXTURE_FORMAT_PTC22,                /** (19) PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP. */
-    BGFX_TEXTURE_FORMAT_PTC24,                /** (20) PVRTC2 RGBA 4BPP               */
+    BGFX_TEXTURE_FORMAT_PTC24,                /** (20) PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_ATC,                  /** (21) ATC RGB 4BPP                   */
+    BGFX_TEXTURE_FORMAT_ATC,                  /** (21) AMD Texture Compression. 3-channel RGB. 4 BPP. */
-    BGFX_TEXTURE_FORMAT_ATCE,                 /** (22) ATCE RGBA 8 BPP explicit alpha */
+    BGFX_TEXTURE_FORMAT_ATCE,                 /** (22) AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_ATCI,                 /** (23) ATCI RGBA 8 BPP interpolated alpha */
+    BGFX_TEXTURE_FORMAT_ATCI,                 /** (23) AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC4X4,              /** (24) ASTC 4x4 8.0 BPP               */
+    BGFX_TEXTURE_FORMAT_ASTC4X4,              /** (24) Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC5X4,              /** (25) ASTC 5x4 6.40 BPP              */
+    BGFX_TEXTURE_FORMAT_ASTC5X4,              /** (25) Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC5X5,              /** (26) ASTC 5x5 5.12 BPP              */
+    BGFX_TEXTURE_FORMAT_ASTC5X5,              /** (26) Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC6X5,              /** (27) ASTC 6x5 4.27 BPP              */
+    BGFX_TEXTURE_FORMAT_ASTC6X5,              /** (27) Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC6X6,              /** (28) ASTC 6x6 3.56 BPP              */
+    BGFX_TEXTURE_FORMAT_ASTC6X6,              /** (28) Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC8X5,              /** (29) ASTC 8x5 3.20 BPP              */
+    BGFX_TEXTURE_FORMAT_ASTC8X5,              /** (29) Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC8X6,              /** (30) ASTC 8x6 2.67 BPP              */
+    BGFX_TEXTURE_FORMAT_ASTC8X6,              /** (30) Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC8X8,              /** (31) ASTC 8x8 2.00 BPP              */
+    BGFX_TEXTURE_FORMAT_ASTC8X8,              /** (31) Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC10X5,             /** (32) ASTC 10x5 2.56 BPP             */
+    BGFX_TEXTURE_FORMAT_ASTC10X5,             /** (32) Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC10X6,             /** (33) ASTC 10x6 2.13 BPP             */
+    BGFX_TEXTURE_FORMAT_ASTC10X6,             /** (33) Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC10X8,             /** (34) ASTC 10x8 1.60 BPP             */
+    BGFX_TEXTURE_FORMAT_ASTC10X8,             /** (34) Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC10X10,            /** (35) ASTC 10x10 1.28 BPP            */
+    BGFX_TEXTURE_FORMAT_ASTC10X10,            /** (35) Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC12X10,            /** (36) ASTC 12x10 1.07 BPP            */
+    BGFX_TEXTURE_FORMAT_ASTC12X10,            /** (36) Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP. */
-    BGFX_TEXTURE_FORMAT_ASTC12X12,            /** (37) ASTC 12x12 0.89 BPP            */
+    BGFX_TEXTURE_FORMAT_ASTC12X12,            /** (37) Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP. */
     BGFX_TEXTURE_FORMAT_UNKNOWN,              /** (38) Compressed formats above.      */
-    BGFX_TEXTURE_FORMAT_R1,                   /** (39)                                */
+    BGFX_TEXTURE_FORMAT_R1,                   /** (39) 1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP. */
-    BGFX_TEXTURE_FORMAT_A8,                   /** (40)                                */
+    BGFX_TEXTURE_FORMAT_A8,                   /** (40) 8-bit single-channel alpha, unsigned normalized. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_R8,                   /** (41)                                */
+    BGFX_TEXTURE_FORMAT_R8,                   /** (41) 8-bit single-channel red, unsigned normalized. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_R8I,                  /** (42)                                */
+    BGFX_TEXTURE_FORMAT_R8I,                  /** (42) 8-bit single-channel red, signed integer. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_R8U,                  /** (43)                                */
+    BGFX_TEXTURE_FORMAT_R8U,                  /** (43) 8-bit single-channel red, unsigned integer. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_R8S,                  /** (44)                                */
+    BGFX_TEXTURE_FORMAT_R8S,                  /** (44) 8-bit single-channel red, signed normalized. 8 BPP. */
-    BGFX_TEXTURE_FORMAT_R16,                  /** (45)                                */
+    BGFX_TEXTURE_FORMAT_R16,                  /** (45) 16-bit single-channel red, unsigned normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_R16I,                 /** (46)                                */
+    BGFX_TEXTURE_FORMAT_R16I,                 /** (46) 16-bit single-channel red, signed integer. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_R16U,                 /** (47)                                */
+    BGFX_TEXTURE_FORMAT_R16U,                 /** (47) 16-bit single-channel red, unsigned integer. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_R16F,                 /** (48)                                */
+    BGFX_TEXTURE_FORMAT_R16F,                 /** (48) 16-bit single-channel red, half-precision floating point. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_R16S,                 /** (49)                                */
+    BGFX_TEXTURE_FORMAT_R16S,                 /** (49) 16-bit single-channel red, signed normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_R32I,                 /** (50)                                */
+    BGFX_TEXTURE_FORMAT_R32I,                 /** (50) 32-bit single-channel red, signed integer. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_R32U,                 /** (51)                                */
+    BGFX_TEXTURE_FORMAT_R32U,                 /** (51) 32-bit single-channel red, unsigned integer. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_R32F,                 /** (52)                                */
+    BGFX_TEXTURE_FORMAT_R32F,                 /** (52) 32-bit single-channel red, full-precision floating point. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RG8,                  /** (53)                                */
+    BGFX_TEXTURE_FORMAT_RG8,                  /** (53) Two 8-bit channels (red, green), unsigned normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_RG8I,                 /** (54)                                */
+    BGFX_TEXTURE_FORMAT_RG8I,                 /** (54) Two 8-bit channels (red, green), signed integer. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_RG8U,                 /** (55)                                */
+    BGFX_TEXTURE_FORMAT_RG8U,                 /** (55) Two 8-bit channels (red, green), unsigned integer. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_RG8S,                 /** (56)                                */
+    BGFX_TEXTURE_FORMAT_RG8S,                 /** (56) Two 8-bit channels (red, green), signed normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_RG16,                 /** (57)                                */
+    BGFX_TEXTURE_FORMAT_RG16,                 /** (57) Two 16-bit channels (red, green), unsigned normalized. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RG16I,                /** (58)                                */
+    BGFX_TEXTURE_FORMAT_RG16I,                /** (58) Two 16-bit channels (red, green), signed integer. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RG16U,                /** (59)                                */
+    BGFX_TEXTURE_FORMAT_RG16U,                /** (59) Two 16-bit channels (red, green), unsigned integer. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RG16F,                /** (60)                                */
+    BGFX_TEXTURE_FORMAT_RG16F,                /** (60) Two 16-bit channels (red, green), half-precision floating point. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RG16S,                /** (61)                                */
+    BGFX_TEXTURE_FORMAT_RG16S,                /** (61) Two 16-bit channels (red, green), signed normalized. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RG32I,                /** (62)                                */
+    BGFX_TEXTURE_FORMAT_RG32I,                /** (62) Two 32-bit channels (red, green), signed integer. 64 BPP. */
-    BGFX_TEXTURE_FORMAT_RG32U,                /** (63)                                */
+    BGFX_TEXTURE_FORMAT_RG32U,                /** (63) Two 32-bit channels (red, green), unsigned integer. 64 BPP. */
-    BGFX_TEXTURE_FORMAT_RG32F,                /** (64)                                */
+    BGFX_TEXTURE_FORMAT_RG32F,                /** (64) Two 32-bit channels (red, green), full-precision floating point. 64 BPP. */
-    BGFX_TEXTURE_FORMAT_RGB8,                 /** (65)                                */
+    BGFX_TEXTURE_FORMAT_RGB8,                 /** (65) Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP. */
-    BGFX_TEXTURE_FORMAT_RGB8I,                /** (66)                                */
+    BGFX_TEXTURE_FORMAT_RGB8I,                /** (66) Three 8-bit channels (red, green, blue), signed integer. 24 BPP. */
-    BGFX_TEXTURE_FORMAT_RGB8U,                /** (67)                                */
+    BGFX_TEXTURE_FORMAT_RGB8U,                /** (67) Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP. */
-    BGFX_TEXTURE_FORMAT_RGB8S,                /** (68)                                */
+    BGFX_TEXTURE_FORMAT_RGB8S,                /** (68) Three 8-bit channels (red, green, blue), signed normalized. 24 BPP. */
-    BGFX_TEXTURE_FORMAT_RGB9E5F,              /** (69)                                */
+    BGFX_TEXTURE_FORMAT_RGB9E5F,              /** (69) Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_BGRA8,                /** (70)                                */
+    BGFX_TEXTURE_FORMAT_BGRA8,                /** (70) Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA8,                /** (71)                                */
+    BGFX_TEXTURE_FORMAT_RGBA8,                /** (71) Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA8I,               /** (72)                                */
+    BGFX_TEXTURE_FORMAT_RGBA8I,               /** (72) Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA8U,               /** (73)                                */
+    BGFX_TEXTURE_FORMAT_RGBA8U,               /** (73) Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA8S,               /** (74)                                */
+    BGFX_TEXTURE_FORMAT_RGBA8S,               /** (74) Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA16,               /** (75)                                */
+    BGFX_TEXTURE_FORMAT_RGBA16,               /** (75) Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA16I,              /** (76)                                */
+    BGFX_TEXTURE_FORMAT_RGBA16I,              /** (76) Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA16U,              /** (77)                                */
+    BGFX_TEXTURE_FORMAT_RGBA16U,              /** (77) Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA16F,              /** (78)                                */
+    BGFX_TEXTURE_FORMAT_RGBA16F,              /** (78) Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA16S,              /** (79)                                */
+    BGFX_TEXTURE_FORMAT_RGBA16S,              /** (79) Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA32I,              /** (80)                                */
+    BGFX_TEXTURE_FORMAT_RGBA32I,              /** (80) Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA32U,              /** (81)                                */
+    BGFX_TEXTURE_FORMAT_RGBA32U,              /** (81) Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA32F,              /** (82)                                */
+    BGFX_TEXTURE_FORMAT_RGBA32F,              /** (82) Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP. */
-    BGFX_TEXTURE_FORMAT_B5G6R5,               /** (83)                                */
+    BGFX_TEXTURE_FORMAT_B5G6R5,               /** (83) Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_R5G6B5,               /** (84)                                */
+    BGFX_TEXTURE_FORMAT_R5G6B5,               /** (84) Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_BGRA4,                /** (85)                                */
+    BGFX_TEXTURE_FORMAT_BGRA4,                /** (85) Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_RGBA4,                /** (86)                                */
+    BGFX_TEXTURE_FORMAT_RGBA4,                /** (86) Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_BGR5A1,               /** (87)                                */
+    BGFX_TEXTURE_FORMAT_BGR5A1,               /** (87) Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_RGB5A1,               /** (88)                                */
+    BGFX_TEXTURE_FORMAT_RGB5A1,               /** (88) Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_RGB10A2,              /** (89)                                */
+    BGFX_TEXTURE_FORMAT_RGB10A2,              /** (89) Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_RG11B10F,             /** (90)                                */
+    BGFX_TEXTURE_FORMAT_RG11B10F,             /** (90) Packed 32-bit, 11-bit red, 11-bit green, 10-bit blue, unsigned floating point. No alpha. 32 BPP. */
     BGFX_TEXTURE_FORMAT_UNKNOWNDEPTH,         /** (91) Depth formats below.           */
-    BGFX_TEXTURE_FORMAT_D16,                  /** (92)                                */
+    BGFX_TEXTURE_FORMAT_D16,                  /** (92) 16-bit depth, unsigned normalized. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_D24,                  /** (93)                                */
+    BGFX_TEXTURE_FORMAT_D24,                  /** (93) 24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP. */
-    BGFX_TEXTURE_FORMAT_D24S8,                /** (94)                                */
+    BGFX_TEXTURE_FORMAT_D24S8,                /** (94) 24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_D32,                  /** (95)                                */
+    BGFX_TEXTURE_FORMAT_D32,                  /** (95) 32-bit depth, unsigned normalized. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_D16F,                 /** (96)                                */
+    BGFX_TEXTURE_FORMAT_D16F,                 /** (96) 16-bit depth, floating point. 16 BPP. */
-    BGFX_TEXTURE_FORMAT_D24F,                 /** (97)                                */
+    BGFX_TEXTURE_FORMAT_D24F,                 /** (97) 24-bit depth, floating point (stored as 32-bit). 32 BPP. */
-    BGFX_TEXTURE_FORMAT_D32F,                 /** (98)                                */
+    BGFX_TEXTURE_FORMAT_D32F,                 /** (98) 32-bit depth, floating point. 32 BPP. */
-    BGFX_TEXTURE_FORMAT_D0S8,                 /** (99)                                */
+    BGFX_TEXTURE_FORMAT_D0S8,                 /** (99) 8-bit stencil only, no depth. 8 BPP. */
 
     BGFX_TEXTURE_FORMAT_COUNT
 
@@ -1254,9 +1254,29 @@ BGFX_C_API void bgfx_shutdown(void);
 BGFX_C_API void bgfx_reset(uint32_t _width, uint32_t _height, uint32_t _flags, bgfx_texture_format_t _format);
 
 /**
- * Advance to next frame. When using multithreaded renderer, this call
+ * Advance to next frame. This is the main frame-advancement call on the
- * just swaps internal buffers, kicks render thread, and returns. In
+ * API thread (the thread from which `bgfx::init` was called).
- * singlethreaded renderer this call does frame rendering.
+ *
+ * **Multithreaded renderer** (`BGFX_CONFIG_MULTITHREADED=1`, default):
+ * This call waits for the render thread to finish processing the previous
+ * frame, then swaps internal submit/render buffers, signals the render
+ * thread to begin processing the new frame via `bgfx::renderFrame`, and
+ * returns immediately. The render thread and API thread then run in
+ * parallel: the API thread builds the next frame while the render thread
+ * executes GPU commands for the current frame.
+ *
+ * **Single-threaded renderer** (`BGFX_CONFIG_MULTITHREADED=0`, or when
+ * `bgfx::renderFrame` and `bgfx::init` are called from the same thread):
+ * This call swaps internal buffers and performs frame rendering inline
+ * (internally calls `bgfx::renderFrame`), then returns.
+ *
+ * @remarks
+ *   Must be called from the API thread (the thread that called
+ *   `bgfx::init`). In multithreaded mode, this call synchronizes with
+ *   `bgfx::renderFrame` running on the render thread via semaphores:
+ *   `bgfx::frame` waits for the render thread to finish, then posts a
+ *   signal that `bgfx::renderFrame` waits on to begin the next frame.
+ *   See also: `bgfx::renderFrame`.
  *
  * @param[in] _flags Frame flags. See: `BGFX_FRAME_*` for more info.
  *    - `BGFX_FRAME_NONE` - No frame flag.
@@ -3087,16 +3107,43 @@ BGFX_C_API void bgfx_encoder_blit(bgfx_encoder_t* _this, bgfx_view_id_t _id, bgf
 BGFX_C_API void bgfx_request_screen_shot(bgfx_frame_buffer_handle_t _handle, const char* _filePath);
 
 /**
- * Render frame.
+ * Render frame. Executes the actual GPU rendering work for one frame.
  *
- * @attention `bgfx::renderFrame` is blocking call. It waits for
+ * In the default **multithreaded** configuration, `bgfx::renderFrame` runs
- *   `bgfx::frame` to be called from API thread to process frame.
+ * on the **render thread** while `bgfx::frame` runs on the **API thread**.
- *   If timeout value is passed call will timeout and return even
+ * Their interaction is as follows:
- *   if `bgfx::frame` is not called.
  *
- * @warning This call should be only used on platforms that don't
+ *   1. The render thread calls `bgfx::renderFrame`, which blocks waiting
- *   allow creating separate rendering thread. If it is called before
+ *      for the API thread to signal that a new frame is ready.
- *   to bgfx::init, render thread won't be created by bgfx::init call.
+ *   2. On the API thread, `bgfx::frame` finishes building the frame,
+ *      swaps internal submit/render buffers, and signals the render thread.
+ *   3. `bgfx::renderFrame` wakes up, executes pre-render commands,
+ *      submits GPU draw calls, executes post-render commands, flips the
+ *      back buffer, then signals back to the API thread that rendering
+ *      is complete.
+ *   4. The API thread's next `bgfx::frame` call waits for this completion
+ *      signal before swapping buffers again.
+ *
+ * This double-buffered semaphore handshake allows the API thread and
+ * render thread to run in parallel, overlapping CPU frame building with
+ * GPU rendering.
+ *
+ * @attention `bgfx::renderFrame` is a blocking call. It waits for
+ *   `bgfx::frame` to be called from the API thread to process the frame.
+ *   If a timeout value is passed, the call will return
+ *   `RenderFrame::Timeout` even if `bgfx::frame` has not been called.
+ *   A value of -1 (default) means wait indefinitely (up to
+ *   `BGFX_CONFIG_API_SEMAPHORE_TIMEOUT`).
+ *
+ * @warning This call should only be used on platforms that don't allow
+ *   creating a separate rendering thread. If it is called before
+ *   `bgfx::init`, the internal render thread won't be created by the
+ *   `bgfx::init` call, and the user is responsible for calling
+ *   `bgfx::renderFrame` on the render thread each frame. If both
+ *   `bgfx::renderFrame` and `bgfx::init` are called from the same
+ *   thread, bgfx operates in single-threaded mode and `bgfx::frame`
+ *   will internally invoke `bgfx::renderFrame` automatically.
+ *   See also: `bgfx::frame`.
  *
  * @param[in] _msecs Timeout in milliseconds.
  *

scripts/bgfx.idl

@@ -535,106 +535,106 @@ enum.AttribType { comment = "Attribute types:", section = "Vertex Buffers" }
 ---
 --- @attention Availability depends on Caps (see: formats).
 enum.TextureFormat { comment = "Texture formats:", section = "Textures" }
-	.BC1       --- DXT1 R5G6B5A1
+	.BC1          --- Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP.
-	.BC2       --- DXT3 R5G6B5A4
+	.BC2          --- Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP.
-	.BC3       --- DXT5 R5G6B5A8
+	.BC3          --- Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP.
-	.BC4       --- LATC1/ATI1 R8
+	.BC4          --- Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP.
-	.BC5       --- LATC2/ATI2 RG8
+	.BC5          --- Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP.
-	.BC6H      --- BC6H RGB16F
+	.BC6H         --- Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP.
-	.BC7       --- BC7 RGB 4-7 bits per color channel, 0-8 bits alpha
+	.BC7          --- RGB 4-7 bits per color channel, 0-8 bits alpha. Block Compression 7. High-quality RGBA, 4-7 bits per color, 0-8 bits alpha. 8 BPP.
-	.ETC1      --- ETC1 RGB8
+	.ETC1         --- Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP.
-	.ETC2      --- ETC2 RGB8
+	.ETC2         --- Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP.
-	.ETC2A     --- ETC2 RGBA8
+	.ETC2A        --- Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP.
-	.ETC2A1    --- ETC2 RGB8A1
+	.ETC2A1       --- Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP.
-	.EACR11    --- EAC R11 UNORM
+	.EACR11       --- ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP.
-	.EACR11S   --- EAC R11 SNORM
+	.EACR11S      --- ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP.
-	.EACRG11   --- EAC RG11 UNORM
+	.EACRG11      --- ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP.
-	.EACRG11S  --- EAC RG11 SNORM
+	.EACRG11S     --- ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP.
-	.PTC12     --- PVRTC1 RGB 2BPP
+	.PTC12        --- PowerVR Texture Compression v1. 3-channel RGB. 2 BPP.
-	.PTC14     --- PVRTC1 RGB 4BPP
+	.PTC14        --- PowerVR Texture Compression v1. 3-channel RGB. 4 BPP.
-	.PTC12A    --- PVRTC1 RGBA 2BPP
+	.PTC12A       --- PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP.
-	.PTC14A    --- PVRTC1 RGBA 4BPP
+	.PTC14A       --- PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP.
-	.PTC22     --- PVRTC2 RGBA 2BPP
+	.PTC22        --- PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP.
-	.PTC24     --- PVRTC2 RGBA 4BPP
+	.PTC24        --- PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP.
-	.ATC       --- ATC RGB 4BPP
+	.ATC          --- AMD Texture Compression. 3-channel RGB. 4 BPP.
-	.ATCE      --- ATCE RGBA 8 BPP explicit alpha
+	.ATCE         --- AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP.
-	.ATCI      --- ATCI RGBA 8 BPP interpolated alpha
+	.ATCI         --- AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP.
-	.ASTC4x4   --- ASTC 4x4 8.0 BPP
+	.ASTC4x4      --- Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP.
-	.ASTC5x4   --- ASTC 5x4 6.40 BPP
+	.ASTC5x4      --- Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP.
-	.ASTC5x5   --- ASTC 5x5 5.12 BPP
+	.ASTC5x5      --- Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP.
-	.ASTC6x5   --- ASTC 6x5 4.27 BPP
+	.ASTC6x5      --- Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP.
-	.ASTC6x6   --- ASTC 6x6 3.56 BPP
+	.ASTC6x6      --- Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP.
-	.ASTC8x5   --- ASTC 8x5 3.20 BPP
+	.ASTC8x5      --- Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP.
-	.ASTC8x6   --- ASTC 8x6 2.67 BPP
+	.ASTC8x6      --- Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP.
-	.ASTC8x8   --- ASTC 8x8 2.00 BPP
+	.ASTC8x8      --- Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP.
-	.ASTC10x5  --- ASTC 10x5 2.56 BPP
+	.ASTC10x5     --- Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP.
-	.ASTC10x6  --- ASTC 10x6 2.13 BPP
+	.ASTC10x6     --- Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP.
-	.ASTC10x8  --- ASTC 10x8 1.60 BPP
+	.ASTC10x8     --- Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP.
-	.ASTC10x10 --- ASTC 10x10 1.28 BPP
+	.ASTC10x10    --- Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP.
-	.ASTC12x10 --- ASTC 12x10 1.07 BPP
+	.ASTC12x10    --- Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP.
-	.ASTC12x12 --- ASTC 12x12 0.89 BPP
+	.ASTC12x12    --- Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP.
 	.Unknown      --- Compressed formats above.
-	.R1
+	.R1           --- 1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP.
-	.A8
+	.A8           --- 8-bit single-channel alpha, unsigned normalized. 8 BPP.
-	.R8
+	.R8           --- 8-bit single-channel red, unsigned normalized. 8 BPP.
-	.R8I
+	.R8I          --- 8-bit single-channel red, signed integer. 8 BPP.
-	.R8U
+	.R8U          --- 8-bit single-channel red, unsigned integer. 8 BPP.
-	.R8S
+	.R8S          --- 8-bit single-channel red, signed normalized. 8 BPP.
-	.R16
+	.R16          --- 16-bit single-channel red, unsigned normalized. 16 BPP.
-	.R16I
+	.R16I         --- 16-bit single-channel red, signed integer. 16 BPP.
-	.R16U
+	.R16U         --- 16-bit single-channel red, unsigned integer. 16 BPP.
-	.R16F
+	.R16F         --- 16-bit single-channel red, half-precision floating point. 16 BPP.
-	.R16S
+	.R16S         --- 16-bit single-channel red, signed normalized. 16 BPP.
-	.R32I
+	.R32I         --- 32-bit single-channel red, signed integer. 32 BPP.
-	.R32U
+	.R32U         --- 32-bit single-channel red, unsigned integer. 32 BPP.
-	.R32F
+	.R32F         --- 32-bit single-channel red, full-precision floating point. 32 BPP.
-	.RG8
+	.RG8          --- Two 8-bit channels (red, green), unsigned normalized. 16 BPP.
-	.RG8I
+	.RG8I         --- Two 8-bit channels (red, green), signed integer. 16 BPP.
-	.RG8U
+	.RG8U         --- Two 8-bit channels (red, green), unsigned integer. 16 BPP.
-	.RG8S
+	.RG8S         --- Two 8-bit channels (red, green), signed normalized. 16 BPP.
-	.RG16
+	.RG16         --- Two 16-bit channels (red, green), unsigned normalized. 32 BPP.
-	.RG16I
+	.RG16I        --- Two 16-bit channels (red, green), signed integer. 32 BPP.
-	.RG16U
+	.RG16U        --- Two 16-bit channels (red, green), unsigned integer. 32 BPP.
-	.RG16F
+	.RG16F        --- Two 16-bit channels (red, green), half-precision floating point. 32 BPP.
-	.RG16S
+	.RG16S        --- Two 16-bit channels (red, green), signed normalized. 32 BPP.
-	.RG32I
+	.RG32I        --- Two 32-bit channels (red, green), signed integer. 64 BPP.
-	.RG32U
+	.RG32U        --- Two 32-bit channels (red, green), unsigned integer. 64 BPP.
-	.RG32F
+	.RG32F        --- Two 32-bit channels (red, green), full-precision floating point. 64 BPP.
-	.RGB8
+	.RGB8         --- Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP.
-	.RGB8I
+	.RGB8I        --- Three 8-bit channels (red, green, blue), signed integer. 24 BPP.
-	.RGB8U
+	.RGB8U        --- Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP.
-	.RGB8S
+	.RGB8S        --- Three 8-bit channels (red, green, blue), signed normalized. 24 BPP.
-	.RGB9E5F
+	.RGB9E5F      --- Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP.
-	.BGRA8
+	.BGRA8        --- Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP.
-	.RGBA8
+	.RGBA8        --- Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP.
-	.RGBA8I
+	.RGBA8I       --- Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP.
-	.RGBA8U
+	.RGBA8U       --- Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP.
-	.RGBA8S
+	.RGBA8S       --- Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP.
-	.RGBA16
+	.RGBA16       --- Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP.
-	.RGBA16I
+	.RGBA16I      --- Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP.
-	.RGBA16U
+	.RGBA16U      --- Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP.
-	.RGBA16F
+	.RGBA16F      --- Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP.
-	.RGBA16S
+	.RGBA16S      --- Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP.
-	.RGBA32I
+	.RGBA32I      --- Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP.
-	.RGBA32U
+	.RGBA32U      --- Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP.
-	.RGBA32F
+	.RGBA32F      --- Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP.
-	.B5G6R5
+	.B5G6R5       --- Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP.
-	.R5G6B5
+	.R5G6B5       --- Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP.
-	.BGRA4
+	.BGRA4        --- Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP.
-	.RGBA4
+	.RGBA4        --- Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP.
-	.BGR5A1
+	.BGR5A1       --- Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP.
-	.RGB5A1
+	.RGB5A1       --- Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP.
-	.RGB10A2
+	.RGB10A2      --- Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP.
-	.RG11B10F
+	.RG11B10F     --- Packed 32-bit, 11-bit red, 11-bit green, 10-bit blue, unsigned floating point. No alpha. 32 BPP.
 	.UnknownDepth --- Depth formats below.
-	.D16
+	.D16          --- 16-bit depth, unsigned normalized. 16 BPP.
-	.D24
+	.D24          --- 24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP.
-	.D24S8
+	.D24S8        --- 24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP.
-	.D32
+	.D32          --- 32-bit depth, unsigned normalized. 32 BPP.
-	.D16F
+	.D16F         --- 16-bit depth, floating point. 16 BPP.
-	.D24F
+	.D24F         --- 24-bit depth, floating point (stored as 32-bit). 32 BPP.
-	.D32F
+	.D32F         --- 32-bit depth, floating point. 32 BPP.
-	.D0S8
+	.D0S8         --- 8-bit stencil only, no depth. 8 BPP.
 	()
 
 --- Uniform type enum.
@@ -1244,9 +1244,30 @@ func.reset { section = "Reset" }
 	.format "TextureFormat::Enum"    --- Texture format. See: `TextureFormat::Enum`.
 	 { default = "TextureFormat::Count" }
 
---- Advance to next frame. When using multithreaded renderer, this call
+--- Advance to next frame. This is the main frame-advancement call on the
---- just swaps internal buffers, kicks render thread, and returns. In
+--- API thread (the thread from which `bgfx::init` was called).
---- singlethreaded renderer this call does frame rendering.
+---
+--- **Multithreaded renderer** (`BGFX_CONFIG_MULTITHREADED=1`, default):
+--- This call waits for the render thread to finish processing the previous
+--- frame, then swaps internal submit/render buffers, signals the render
+--- thread to begin processing the new frame via `bgfx::renderFrame`, and
+--- returns immediately. The render thread and API thread then run in
+--- parallel: the API thread builds the next frame while the render thread
+--- executes GPU commands for the current frame.
+---
+--- **Single-threaded renderer** (`BGFX_CONFIG_MULTITHREADED=0`, or when
+--- `bgfx::renderFrame` and `bgfx::init` are called from the same thread):
+--- This call swaps internal buffers and performs frame rendering inline
+--- (internally calls `bgfx::renderFrame`), then returns.
+---
+--- @remarks
+---   Must be called from the API thread (the thread that called
+---   `bgfx::init`). In multithreaded mode, this call synchronizes with
+---   `bgfx::renderFrame` running on the render thread via semaphores:
+---   `bgfx::frame` waits for the render thread to finish, then posts a
+---   signal that `bgfx::renderFrame` waits on to begin the next frame.
+---   See also: `bgfx::renderFrame`.
+---
 func.frame { section = "Frame" }
 	"uint32_t"                       --- Current frame number. This might be used in conjunction with
 	                                 --- double/multi buffering data outside the library and passing it to
@@ -2782,16 +2803,43 @@ func.requestScreenShot { section = "Miscellaneous" }
 	                              --- made for main window back buffer.
 	.filePath "const char*"       --- Will be passed to `bgfx::CallbackI::screenShot` callback.
 
---- Render frame.
+--- Render frame. Executes the actual GPU rendering work for one frame.
 ---
---- @attention `bgfx::renderFrame` is blocking call. It waits for
+--- In the default **multithreaded** configuration, `bgfx::renderFrame` runs
----   `bgfx::frame` to be called from API thread to process frame.
+--- on the **render thread** while `bgfx::frame` runs on the **API thread**.
----   If timeout value is passed call will timeout and return even
+--- Their interaction is as follows:
----   if `bgfx::frame` is not called.
 ---
---- @warning This call should be only used on platforms that don't
+---   1. The render thread calls `bgfx::renderFrame`, which blocks waiting
----   allow creating separate rendering thread. If it is called before
+---      for the API thread to signal that a new frame is ready.
----   to bgfx::init, render thread won't be created by bgfx::init call.
+---   2. On the API thread, `bgfx::frame` finishes building the frame,
+---      swaps internal submit/render buffers, and signals the render thread.
+---   3. `bgfx::renderFrame` wakes up, executes pre-render commands,
+---      submits GPU draw calls, executes post-render commands, flips the
+---      back buffer, then signals back to the API thread that rendering
+---      is complete.
+---   4. The API thread's next `bgfx::frame` call waits for this completion
+---      signal before swapping buffers again.
+---
+--- This double-buffered semaphore handshake allows the API thread and
+--- render thread to run in parallel, overlapping CPU frame building with
+--- GPU rendering.
+---
+--- @attention `bgfx::renderFrame` is a blocking call. It waits for
+---   `bgfx::frame` to be called from the API thread to process the frame.
+---   If a timeout value is passed, the call will return
+---   `RenderFrame::Timeout` even if `bgfx::frame` has not been called.
+---   A value of -1 (default) means wait indefinitely (up to
+---   `BGFX_CONFIG_API_SEMAPHORE_TIMEOUT`).
+---
+--- @warning This call should only be used on platforms that don't allow
+---   creating a separate rendering thread. If it is called before
+---   `bgfx::init`, the internal render thread won't be created by the
+---   `bgfx::init` call, and the user is responsible for calling
+---   `bgfx::renderFrame` on the render thread each frame. If both
+---   `bgfx::renderFrame` and `bgfx::init` are called from the same
+---   thread, bgfx operates in single-threaded mode and `bgfx::frame`
+---   will internally invoke `bgfx::renderFrame` automatically.
+---   See also: `bgfx::frame`.
 ---
 func.renderFrame { section = "Platform specific" }
 	"RenderFrame::Enum" --- Current renderer context state. See: `bgfx::RenderFrame`.

scripts/docs-rst.lua

@@ -107,6 +107,9 @@ function gen.gen()
 		r[#r+1] = s or ""
 	end
 
+	emit(".. AUTO GENERATED! DO NOT EDIT!")
+	emit()
+
 	-- Determine leaf sections and build parent paths for item lookup.
 	-- A leaf section is one not immediately followed by a deeper-level section.
 	-- The path is "parent_title/title" (used to disambiguate duplicate titles).

src/config.h

@@ -175,21 +175,28 @@
 #	error "Can't define both BGFX_CONFIG_RENDERER_OPENGL and BGFX_CONFIG_RENDERER_OPENGLES"
 #endif // BGFX_CONFIG_RENDERER_OPENGL && BGFX_CONFIG_RENDERER_OPENGLES
 
-/// Enable use of extensions.
+/// Enable use of renderer-specific API extensions (e.g. OpenGL extensions,
+/// Vulkan extensions). Default is 1 (enabled).
 #ifndef BGFX_CONFIG_RENDERER_USE_EXTENSIONS
 #	define BGFX_CONFIG_RENDERER_USE_EXTENSIONS 1
 #endif // BGFX_CONFIG_RENDERER_USE_EXTENSIONS
 
+/// Enable use of staging buffers in the Direct3D 11 renderer for texture and
+/// buffer updates. Default is 0 (disabled). When enabled, updates go through
+/// a staging buffer instead of using Map/Unmap directly.
 #ifndef BGFX_CONFIG_RENDERER_DIRECT3D11_USE_STAGING_BUFFER
 #	define BGFX_CONFIG_RENDERER_DIRECT3D11_USE_STAGING_BUFFER 0
 #endif // BGFX_CONFIG_RENDERER_DIRECT3D11_USE_STAGING_BUFFER
 
-/// Configure the amount of max descriptor sets per frame for Vulkan
+/// Maximum number of Vulkan descriptor sets allocated per frame. Default is
+/// 1024. Each draw/compute call may consume one descriptor set.
 #ifndef BGFX_CONFIG_RENDERER_VULKAN_MAX_DESCRIPTOR_SETS_PER_FRAME
 #	define BGFX_CONFIG_RENDERER_VULKAN_MAX_DESCRIPTOR_SETS_PER_FRAME 1024
 #endif // BGFX_CONFIG_RENDERER_VULKAN_MAX_DESCRIPTOR_SETS_PER_FRAME
 
-/// Enable use of tinystl.
+/// Enable use of tinystl instead of std containers for internal data
+/// structures. Default is 1 (enabled). Reduces binary size and avoids
+/// std library dependency.
 #ifndef BGFX_CONFIG_USE_TINYSTL
 #	define BGFX_CONFIG_USE_TINYSTL 1
 #endif // BGFX_CONFIG_USE_TINYSTL
@@ -224,34 +231,48 @@
 #	define BGFX_CONFIG_DEBUG_OCCLUSION BGFX_CONFIG_DEBUG
 #endif // BGFX_CONFIG_DEBUG_OCCLUSION
 
+/// Enable/disable multithreaded rendering. When enabled, bgfx can use a
+/// separate render thread for GPU submission. Default is 1 on all platforms
+/// that support threading (0 on Emscripten).
 #ifndef BGFX_CONFIG_MULTITHREADED
 #	define BGFX_CONFIG_MULTITHREADED ( (0 == BX_PLATFORM_EMSCRIPTEN) ? 1 : 0)
 #endif // BGFX_CONFIG_MULTITHREADED
 
+/// Maximum number of draw/compute calls per frame. Default is 65535 (64K - 1).
 #ifndef BGFX_CONFIG_MAX_DRAW_CALLS
 #	define BGFX_CONFIG_MAX_DRAW_CALLS ( (64<<10)-1)
 #endif // BGFX_CONFIG_MAX_DRAW_CALLS
 
+/// Maximum number of blit items per frame. Default is 1024.
 #ifndef BGFX_CONFIG_MAX_BLIT_ITEMS
 #	define BGFX_CONFIG_MAX_BLIT_ITEMS (1<<10)
 #endif // BGFX_CONFIG_MAX_BLIT_ITEMS
 
+/// Maximum number of cached transform matrices. Default is BGFX_CONFIG_MAX_DRAW_CALLS + 1.
+/// Each draw call may reference a transform matrix; this cache stores them for the frame.
 #ifndef BGFX_CONFIG_MAX_MATRIX_CACHE
 #	define BGFX_CONFIG_MAX_MATRIX_CACHE (BGFX_CONFIG_MAX_DRAW_CALLS+1)
 #endif // BGFX_CONFIG_MAX_MATRIX_CACHE
 
+/// Maximum number of cached scissor rectangles per frame. Default is 4096.
 #ifndef BGFX_CONFIG_MAX_RECT_CACHE
 #	define BGFX_CONFIG_MAX_RECT_CACHE (4<<10)
 #endif //  BGFX_CONFIG_MAX_RECT_CACHE
 
+/// Number of bits used for depth in the sort key. Default is 32.
+/// Reducing this allows more bits for other sort key fields.
 #ifndef BGFX_CONFIG_SORT_KEY_NUM_BITS_DEPTH
 #	define BGFX_CONFIG_SORT_KEY_NUM_BITS_DEPTH 32
 #endif // BGFX_CONFIG_SORT_KEY_NUM_BITS_DEPTH
 
+/// Number of bits used for sequence number in the sort key. Default is 20.
+/// Determines maximum draw calls per view in sequential mode (2^20 = ~1M).
 #ifndef BGFX_CONFIG_SORT_KEY_NUM_BITS_SEQ
 #	define BGFX_CONFIG_SORT_KEY_NUM_BITS_SEQ 20
 #endif // BGFX_CONFIG_SORT_KEY_NUM_BITS_SEQ
 
+/// Number of bits used for program index in the sort key. Default is 9.
+/// Determines BGFX_CONFIG_MAX_PROGRAMS (2^9 = 512).
 #ifndef BGFX_CONFIG_SORT_KEY_NUM_BITS_PROGRAM
 #	define BGFX_CONFIG_SORT_KEY_NUM_BITS_PROGRAM 9
 #endif // BGFX_CONFIG_SORT_KEY_NUM_BITS_PROGRAM
@@ -260,6 +281,8 @@
 #define BGFX_CONFIG_MAX_PROGRAMS (1<<BGFX_CONFIG_SORT_KEY_NUM_BITS_PROGRAM)
 static_assert(bx::isPowerOf2(BGFX_CONFIG_MAX_PROGRAMS), "BGFX_CONFIG_MAX_PROGRAMS must be power of 2.");
 
+/// Maximum number of views. Default is 256. Must be a power of 2.
+/// Views are referenced by ViewId (uint16_t).
 #ifndef BGFX_CONFIG_MAX_VIEWS
 #	define BGFX_CONFIG_MAX_VIEWS 256
 #endif // BGFX_CONFIG_MAX_VIEWS
@@ -267,70 +290,92 @@ static_assert(bx::isPowerOf2(BGFX_CONFIG_MAX_VIEWS), "BGFX_CONFIG_MAX_VIEWS must
 
 #define BGFX_CONFIG_MAX_VIEW_NAME_RESERVED 6
 
+/// Maximum length of a view name string. Default is 256.
 #ifndef BGFX_CONFIG_MAX_VIEW_NAME
 #	define BGFX_CONFIG_MAX_VIEW_NAME 256
 #endif // BGFX_CONFIG_MAX_VIEW_NAME
 
+/// Maximum number of vertex layout declarations. Default is 64.
 #ifndef BGFX_CONFIG_MAX_VERTEX_LAYOUTS
 #	define BGFX_CONFIG_MAX_VERTEX_LAYOUTS 64
 #endif // BGFX_CONFIG_MAX_VERTEX_LAYOUTS
 
+/// Maximum number of static index buffer handles. Default is 4096.
 #ifndef BGFX_CONFIG_MAX_INDEX_BUFFERS
 #	define BGFX_CONFIG_MAX_INDEX_BUFFERS (4<<10)
 #endif // BGFX_CONFIG_MAX_INDEX_BUFFERS
 
+/// Maximum number of static vertex buffer handles. Default is 4096.
 #ifndef BGFX_CONFIG_MAX_VERTEX_BUFFERS
 #	define BGFX_CONFIG_MAX_VERTEX_BUFFERS (4<<10)
 #endif // BGFX_CONFIG_MAX_VERTEX_BUFFERS
 
+/// Maximum number of vertex streams per draw call. Default is 4.
 #ifndef BGFX_CONFIG_MAX_VERTEX_STREAMS
 #	define BGFX_CONFIG_MAX_VERTEX_STREAMS 4
 #endif // BGFX_CONFIG_MAX_VERTEX_STREAMS
 
+/// Maximum number of dynamic index buffer handles. Default is 4096.
 #ifndef BGFX_CONFIG_MAX_DYNAMIC_INDEX_BUFFERS
 #	define BGFX_CONFIG_MAX_DYNAMIC_INDEX_BUFFERS (4<<10)
 #endif // BGFX_CONFIG_MAX_DYNAMIC_INDEX_BUFFERS
 
+/// Maximum number of dynamic vertex buffer handles. Default is 4096.
 #ifndef BGFX_CONFIG_MAX_DYNAMIC_VERTEX_BUFFERS
 #	define BGFX_CONFIG_MAX_DYNAMIC_VERTEX_BUFFERS (4<<10)
 #endif // BGFX_CONFIG_MAX_DYNAMIC_VERTEX_BUFFERS
 
+/// Initial size in bytes of the dynamic index buffer backing store. Default is 1 MB.
+/// The backing store grows as needed via sub-allocation.
 #ifndef BGFX_CONFIG_DYNAMIC_INDEX_BUFFER_SIZE
 #	define BGFX_CONFIG_DYNAMIC_INDEX_BUFFER_SIZE (1<<20)
 #endif // BGFX_CONFIG_DYNAMIC_INDEX_BUFFER_SIZE
 
+/// Initial size in bytes of the dynamic vertex buffer backing store. Default is 3 MB.
+/// The backing store grows as needed via sub-allocation.
 #ifndef BGFX_CONFIG_DYNAMIC_VERTEX_BUFFER_SIZE
 #	define BGFX_CONFIG_DYNAMIC_VERTEX_BUFFER_SIZE (3<<20)
 #endif // BGFX_CONFIG_DYNAMIC_VERTEX_BUFFER_SIZE
 
+/// Maximum number of shader handles (vertex + fragment + compute). Default is 512.
 #ifndef BGFX_CONFIG_MAX_SHADERS
 #	define BGFX_CONFIG_MAX_SHADERS 512
 #endif // BGFX_CONFIG_MAX_FRAGMENT_SHADERS
 
+/// Maximum number of texture handles. Default is 4096.
 #ifndef BGFX_CONFIG_MAX_TEXTURES
 #	define BGFX_CONFIG_MAX_TEXTURES (4<<10)
 #endif // BGFX_CONFIG_MAX_TEXTURES
 
+/// Maximum number of texture samplers per draw call. Default is 16.
 #ifndef BGFX_CONFIG_MAX_TEXTURE_SAMPLERS
 #	define BGFX_CONFIG_MAX_TEXTURE_SAMPLERS 16
 #endif // BGFX_CONFIG_MAX_TEXTURE_SAMPLERS
 
+/// Maximum number of frame buffer handles. Default is 128.
 #ifndef BGFX_CONFIG_MAX_FRAME_BUFFERS
 #	define BGFX_CONFIG_MAX_FRAME_BUFFERS 128
 #endif // BGFX_CONFIG_MAX_FRAME_BUFFERS
 
+/// Maximum number of attachments (color + depth/stencil) per frame buffer.
+/// Default is 8.
 #ifndef BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS
 #	define BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS 8
 #endif // BGFX_CONFIG_MAX_FRAME_BUFFER_ATTACHMENTS
 
+/// Maximum number of uniform handles. Default is 512.
 #ifndef BGFX_CONFIG_MAX_UNIFORMS
 #	define BGFX_CONFIG_MAX_UNIFORMS 512
 #endif // BGFX_CONFIG_MAX_UNIFORMS
 
+/// Maximum number of occlusion query handles. Default is 256.
 #ifndef BGFX_CONFIG_MAX_OCCLUSION_QUERIES
 #	define BGFX_CONFIG_MAX_OCCLUSION_QUERIES 256
 #endif // BGFX_CONFIG_MAX_OCCLUSION_QUERIES
 
+/// Minimum initial size in bytes of the resource command buffer (pre/post
+/// render commands for resource creation and updates). Default is 64 KB.
+/// The buffer grows as needed.
 #ifndef BGFX_CONFIG_MIN_RESOURCE_COMMAND_BUFFER_SIZE
 #	define BGFX_CONFIG_MIN_RESOURCE_COMMAND_BUFFER_SIZE (64<<10)
 #endif // BGFX_CONFIG_MIN_RESOURCE_COMMAND_BUFFER_SIZE
@@ -386,58 +431,89 @@ static_assert(bx::isPowerOf2(BGFX_CONFIG_MAX_VIEWS), "BGFX_CONFIG_MAX_VIEWS must
 #   define BGFX_CONFIG_MAX_SCRATCH_STAGING_BUFFER_PER_FRAME_SIZE (32<<20)
 #endif // BGFX_CONFIG_MAX_SCRATCH_STAGING_BUFFER_PER_FRAME_SIZE
 
+/// Maximum number of instance data vec4 attributes per draw call. Default is 5.
+/// Each instance data element is a vec4 (16 bytes). Total instance stride is
+/// BGFX_CONFIG_MAX_INSTANCE_DATA_COUNT * 16 bytes.
 #ifndef BGFX_CONFIG_MAX_INSTANCE_DATA_COUNT
 #	define BGFX_CONFIG_MAX_INSTANCE_DATA_COUNT 5
 #endif // BGFX_CONFIG_MAX_INSTANCE_DATA_COUNT
 
+/// Maximum number of color palette entries. Default is 16.
+/// Color palettes are used with clear color indexing.
 #ifndef BGFX_CONFIG_MAX_COLOR_PALETTE
 #	define BGFX_CONFIG_MAX_COLOR_PALETTE 16
 #endif // BGFX_CONFIG_MAX_COLOR_PALETTE
 
+/// Stride in bytes of each draw indirect command. Fixed at 32 bytes.
 #define BGFX_CONFIG_DRAW_INDIRECT_STRIDE 32
 
+/// Enable internal profiler instrumentation. When enabled, bgfx will emit
+/// profiler scopes for frame, submit, resource, and view operations.
+/// Default is 0 (disabled).
 #ifndef BGFX_CONFIG_PROFILER
 #	define BGFX_CONFIG_PROFILER 0
 #endif // BGFX_CONFIG_PROFILER
 
+/// File path for RenderDoc capture log output. Default is "temp/bgfx".
 #ifndef BGFX_CONFIG_RENDERDOC_LOG_FILEPATH
 #	define BGFX_CONFIG_RENDERDOC_LOG_FILEPATH "temp/bgfx"
 #endif // BGFX_CONFIG_RENDERDOC_LOG_FILEPATH
 
+/// Key(s) to trigger a RenderDoc capture. Default is F11.
 #ifndef BGFX_CONFIG_RENDERDOC_CAPTURE_KEYS
 #	define BGFX_CONFIG_RENDERDOC_CAPTURE_KEYS { eRENDERDOC_Key_F11 }
 #endif // BGFX_CONFIG_RENDERDOC_CAPTURE_KEYS
 
+/// Timeout in milliseconds for the API/render thread semaphore wait.
+/// Default is 5000 ms. If the wait times out, it typically indicates a
+/// deadlock or the other thread has stalled.
 #ifndef BGFX_CONFIG_API_SEMAPHORE_TIMEOUT
 #	define BGFX_CONFIG_API_SEMAPHORE_TIMEOUT (5000)
 #endif // BGFX_CONFIG_API_SEMAPHORE_TIMEOUT
 
+/// Global MIP level-of-detail bias applied to all texture sampling.
+/// Default is 0 (no bias). Positive values select coarser MIP levels,
+/// negative values select finer MIP levels.
 #ifndef BGFX_CONFIG_MIP_LOD_BIAS
 #	define BGFX_CONFIG_MIP_LOD_BIAS 0
 #endif // BGFX_CONFIG_MIP_LOD_BIAS
 
+/// Default maximum number of simultaneous encoders for multithreaded
+/// draw call submission. Default is 8 when multithreaded, 1 otherwise.
+/// Can be overridden at runtime via Limits.maxEncoders in bgfx::Init.
 #ifndef BGFX_CONFIG_DEFAULT_MAX_ENCODERS
 #	define BGFX_CONFIG_DEFAULT_MAX_ENCODERS ( (0 != BGFX_CONFIG_MULTITHREADED) ? 8 : 1)
 #endif // BGFX_CONFIG_DEFAULT_MAX_ENCODERS
 
+/// Maximum number of back buffers for swap chain. Default is 4.
+/// The actual number used is specified via bgfx::Resolution::numBackBuffers.
 #ifndef BGFX_CONFIG_MAX_BACK_BUFFERS
 #	define BGFX_CONFIG_MAX_BACK_BUFFERS 4
 #endif // BGFX_CONFIG_MAX_BACK_BUFFERS
 
+/// Maximum frame latency (number of frames that can be queued ahead).
+/// Default is 3. The actual value is specified via
+/// bgfx::Resolution::maxFrameLatency.
 #ifndef BGFX_CONFIG_MAX_FRAME_LATENCY
 #	define BGFX_CONFIG_MAX_FRAME_LATENCY 3
 #endif // BGFX_CONFIG_MAX_FRAME_LATENCY
 
+/// On laptops with integrated and discrete GPU, prefer selection of the
+/// discrete GPU. Applies to nVidia and AMD on Windows only.
+/// Default is 1 on Windows, 0 elsewhere.
 #ifndef BGFX_CONFIG_PREFER_DISCRETE_GPU
-// On laptops with integrated and discrete GPU, prefer selection of discrete GPU.
-// nVidia and AMD, on Windows only.
 #	define BGFX_CONFIG_PREFER_DISCRETE_GPU BX_PLATFORM_WINDOWS
 #endif // BGFX_CONFIG_PREFER_DISCRETE_GPU
 
+/// Maximum number of screenshot requests that can be queued per frame.
+/// Default is 4.
 #ifndef BGFX_CONFIG_MAX_SCREENSHOTS
 #	define BGFX_CONFIG_MAX_SCREENSHOTS 4
 #endif // BGFX_CONFIG_MAX_SCREENSHOTS
 
+/// When set to 1, disable the legacy non-encoder API (bgfx::setState,
+/// bgfx::submit, etc.) and require all submissions to go through the
+/// Encoder API (bgfx::begin / bgfx::end). Default is 0.
 #ifndef BGFX_CONFIG_ENCODER_API_ONLY
 #	define BGFX_CONFIG_ENCODER_API_ONLY 0
 #endif // BGFX_CONFIG_ENCODER_API_ONLY