diff --git a/bindings/bf/bgfx.bf b/bindings/bf/bgfx.bf index 230888609..2753b877a 100644 --- a/bindings/bf/bgfx.bf +++ b/bindings/bf/bgfx.bf @@ -1618,192 +1618,192 @@ public static class bgfx public enum TextureFormat : uint32 { /// - /// 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, @@ -1811,70 +1811,310 @@ public static class bgfx /// 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 @@ -2735,9 +2975,30 @@ public static class bgfx public static extern void reset(uint32 _width, uint32 _height, uint32 _flags, TextureFormat _format); /// - /// Advance to next frame. When using multithreaded renderer, this call - /// just swaps internal buffers, kicks render thread, and returns. In - /// singlethreaded renderer this call does frame rendering. + /// Advance to next frame. This is the main frame-advancement call on the + /// API thread (the thread from which `bgfx::init` was called). + /// + /// **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`. + /// /// /// /// 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. @@ -4454,16 +4715,43 @@ public static class bgfx public static extern void request_screen_shot(FrameBufferHandle _handle, char8* _filePath); /// - /// Render frame. + /// Render frame. Executes the actual GPU rendering work for one frame. /// - /// @attention `bgfx::renderFrame` is blocking call. It waits for - /// `bgfx::frame` to be called from API thread to process frame. - /// If timeout value is passed call will timeout and return even - /// if `bgfx::frame` is not called. + /// 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: /// - /// @warning This call should be only used on platforms that don't - /// allow creating separate rendering thread. If it is called before - /// to bgfx::init, render thread won't be created by bgfx::init call. + /// 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. + /// + /// @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`. /// /// /// diff --git a/bindings/c3/bgfx.c3 b/bindings/c3/bgfx.c3 index dbcfee793..0a08188ad 100644 --- a/bindings/c3/bgfx.c3 +++ b/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 -// just swaps internal buffers, kicks render thread, and returns. In -// singlethreaded renderer this call does frame rendering. +// Advance to next frame. This is the main frame-advancement call on the +// API thread (the thread from which `bgfx::init` was called). +// +// **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 -// `bgfx::frame` to be called from API thread to process frame. -// If timeout value is passed call will timeout and return even -// if `bgfx::frame` is not called. +// 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: // -// @warning This call should be only used on platforms that don't -// allow creating separate rendering thread. If it is called before -// to bgfx::init, render thread won't be created by bgfx::init call. +// 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. +// +// @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"); diff --git a/bindings/cs/bgfx.cs b/bindings/cs/bgfx.cs index 21a9a901c..2d3c9ce0b 100644 --- a/bindings/cs/bgfx.cs +++ b/bindings/cs/bgfx.cs @@ -1611,192 +1611,192 @@ public static partial class bgfx public enum TextureFormat { /// - /// 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, @@ -1804,70 +1804,310 @@ public static partial class bgfx /// 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 @@ -2685,9 +2925,30 @@ public static partial class bgfx public static extern unsafe void reset(uint _width, uint _height, uint _flags, TextureFormat _format); /// - /// Advance to next frame. When using multithreaded renderer, this call - /// just swaps internal buffers, kicks render thread, and returns. In - /// singlethreaded renderer this call does frame rendering. + /// Advance to next frame. This is the main frame-advancement call on the + /// API thread (the thread from which `bgfx::init` was called). + /// + /// **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`. + /// /// /// /// 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. @@ -4407,16 +4668,43 @@ public static partial class bgfx public static extern unsafe void request_screen_shot(FrameBufferHandle _handle, [MarshalAs(UnmanagedType.LPStr)] string _filePath); /// - /// Render frame. + /// Render frame. Executes the actual GPU rendering work for one frame. /// - /// @attention `bgfx::renderFrame` is blocking call. It waits for - /// `bgfx::frame` to be called from API thread to process frame. - /// If timeout value is passed call will timeout and return even - /// if `bgfx::frame` is not called. + /// 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: /// - /// @warning This call should be only used on platforms that don't - /// allow creating separate rendering thread. If it is called before - /// to bgfx::init, render thread won't be created by bgfx::init call. + /// 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. + /// + /// @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`. /// /// /// diff --git a/bindings/d/package.d b/bindings/d/package.d index 4ba4b809e..0f136c157 100644 --- a/bindings/d/package.d +++ b/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 - * just swaps internal buffers, kicks render thread, and returns. In - * singlethreaded renderer this call does frame rendering. + * Advance to next frame. This is the main frame-advancement call on the + * API thread (the thread from which `bgfx::init` was called). + * + * **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 - * `bgfx::frame` to be called from API thread to process frame. - * If timeout value is passed call will timeout and return even - * if `bgfx::frame` is not called. + * 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: * - * Warning: This call should be only used on platforms that don't - * allow creating separate rendering thread. If it is called before - * to bgfx::init, render thread won't be created by bgfx::init call. + * 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. + * + * 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. diff --git a/bindings/zig/bgfx.zig b/bindings/zig/bgfx.zig index f946c7a7a..d44a732d1 100644 --- a/bindings/zig/bgfx.zig +++ b/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 -/// just swaps internal buffers, kicks render thread, and returns. In -/// singlethreaded renderer this call does frame rendering. +/// Advance to next frame. This is the main frame-advancement call on the +/// API thread (the thread from which `bgfx::init` was called). +/// +/// **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`. +/// /// 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. 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 -/// `bgfx::frame` to be called from API thread to process frame. -/// If timeout value is passed call will timeout and return even -/// if `bgfx::frame` is not called. +/// 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: /// -/// @warning This call should be only used on platforms that don't -/// allow creating separate rendering thread. If it is called before -/// to bgfx::init, render thread won't be created by bgfx::init call. +/// 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. +/// +/// @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`. /// /// Timeout in milliseconds. pub inline fn renderFrame(_msecs: i32) RenderFrame { diff --git a/docs/bgfx.rst b/docs/bgfx.rst index 1d1beed3b..16d87be34 100644 --- a/docs/bgfx.rst +++ b/docs/bgfx.rst @@ -1,3 +1,5 @@ +.. AUTO GENERATED! DO NOT EDIT! + API Reference ============= diff --git a/docs/idl.rst b/docs/idl.rst new file mode 100644 index 000000000..5f42b205f --- /dev/null +++ b/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 `__. + +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/``. diff --git a/docs/index.rst b/docs/index.rst index 8a0961717..b8a65c41d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,4 +19,5 @@ Contents bgfx tools internals + idl license diff --git a/docs/internals.rst b/docs/internals.rst index 00b2fd187..634b9001f 100644 --- a/docs/internals.rst +++ b/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! `__ +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! `__ + +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 `__ +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 `__ -If you're targeting specific mobile hardware, you can find GLES support in their official SDKs: `Adreno -SDK `__, `Mali SDK `__, `PowerVR SDK `__. +If you're targeting specific mobile hardware, you can find GLES support in their official SDKs: `Adreno SDK `__, `Mali SDK `__, `PowerVR SDK `__. All configuration settings are located inside `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. diff --git a/include/bgfx/bgfx.h b/include/bgfx/bgfx.h index 9c776b698..77ef18bce 100644 --- a/include/bgfx/bgfx.h +++ b/include/bgfx/bgfx.h @@ -168,106 +168,106 @@ namespace bgfx /// Texture formats: enum Enum { - BC1, //!< DXT1 R5G6B5A1 - BC2, //!< DXT3 R5G6B5A4 - BC3, //!< DXT5 R5G6B5A8 - BC4, //!< LATC1/ATI1 R8 - BC5, //!< LATC2/ATI2 RG8 - BC6H, //!< BC6H RGB16F - BC7, //!< BC7 RGB 4-7 bits per color channel, 0-8 bits alpha - ETC1, //!< ETC1 RGB8 - ETC2, //!< ETC2 RGB8 - ETC2A, //!< ETC2 RGBA8 - ETC2A1, //!< ETC2 RGB8A1 - EACR11, //!< EAC R11 UNORM - EACR11S, //!< EAC R11 SNORM - EACRG11, //!< EAC RG11 UNORM - EACRG11S, //!< EAC RG11 SNORM - PTC12, //!< PVRTC1 RGB 2BPP - PTC14, //!< PVRTC1 RGB 4BPP - PTC12A, //!< PVRTC1 RGBA 2BPP - PTC14A, //!< PVRTC1 RGBA 4BPP - PTC22, //!< PVRTC2 RGBA 2BPP - PTC24, //!< PVRTC2 RGBA 4BPP - ATC, //!< ATC RGB 4BPP - ATCE, //!< ATCE RGBA 8 BPP explicit alpha - ATCI, //!< ATCI RGBA 8 BPP interpolated alpha - ASTC4x4, //!< ASTC 4x4 8.0 BPP - ASTC5x4, //!< ASTC 5x4 6.40 BPP - ASTC5x5, //!< ASTC 5x5 5.12 BPP - ASTC6x5, //!< ASTC 6x5 4.27 BPP - ASTC6x6, //!< ASTC 6x6 3.56 BPP - ASTC8x5, //!< ASTC 8x5 3.20 BPP - ASTC8x6, //!< ASTC 8x6 2.67 BPP - ASTC8x8, //!< ASTC 8x8 2.00 BPP - ASTC10x5, //!< ASTC 10x5 2.56 BPP - ASTC10x6, //!< ASTC 10x6 2.13 BPP - ASTC10x8, //!< ASTC 10x8 1.60 BPP - ASTC10x10, //!< ASTC 10x10 1.28 BPP - ASTC12x10, //!< ASTC 12x10 1.07 BPP - ASTC12x12, //!< ASTC 12x12 0.89 BPP + BC1, //!< Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP. + BC2, //!< Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP. + BC3, //!< Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP. + BC4, //!< Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP. + BC5, //!< Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP. + BC6H, //!< Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP. + 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, //!< Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP. + ETC2, //!< Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP. + ETC2A, //!< Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP. + ETC2A1, //!< Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP. + EACR11, //!< ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP. + EACR11S, //!< ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP. + EACRG11, //!< ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP. + EACRG11S, //!< ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP. + PTC12, //!< PowerVR Texture Compression v1. 3-channel RGB. 2 BPP. + PTC14, //!< PowerVR Texture Compression v1. 3-channel RGB. 4 BPP. + PTC12A, //!< PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP. + PTC14A, //!< PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP. + PTC22, //!< PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP. + PTC24, //!< PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP. + ATC, //!< AMD Texture Compression. 3-channel RGB. 4 BPP. + ATCE, //!< AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP. + ATCI, //!< AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP. + ASTC4x4, //!< Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP. + ASTC5x4, //!< Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP. + ASTC5x5, //!< Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP. + ASTC6x5, //!< Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP. + ASTC6x6, //!< Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP. + ASTC8x5, //!< Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP. + ASTC8x6, //!< Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP. + ASTC8x8, //!< Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP. + ASTC10x5, //!< Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP. + ASTC10x6, //!< Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP. + ASTC10x8, //!< Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP. + ASTC10x10, //!< Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP. + ASTC12x10, //!< Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP. + ASTC12x12, //!< Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP. Unknown, //!< Compressed formats above. - R1, - A8, - R8, - R8I, - R8U, - R8S, - R16, - R16I, - R16U, - R16F, - R16S, - R32I, - R32U, - R32F, - RG8, - RG8I, - RG8U, - RG8S, - RG16, - RG16I, - RG16U, - RG16F, - RG16S, - RG32I, - RG32U, - RG32F, - RGB8, - RGB8I, - RGB8U, - RGB8S, - RGB9E5F, - BGRA8, - RGBA8, - RGBA8I, - RGBA8U, - RGBA8S, - RGBA16, - RGBA16I, - RGBA16U, - RGBA16F, - RGBA16S, - RGBA32I, - RGBA32U, - RGBA32F, - B5G6R5, - R5G6B5, - BGRA4, - RGBA4, - BGR5A1, - RGB5A1, - RGB10A2, - RG11B10F, + R1, //!< 1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP. + A8, //!< 8-bit single-channel alpha, unsigned normalized. 8 BPP. + R8, //!< 8-bit single-channel red, unsigned normalized. 8 BPP. + R8I, //!< 8-bit single-channel red, signed integer. 8 BPP. + R8U, //!< 8-bit single-channel red, unsigned integer. 8 BPP. + R8S, //!< 8-bit single-channel red, signed normalized. 8 BPP. + R16, //!< 16-bit single-channel red, unsigned normalized. 16 BPP. + R16I, //!< 16-bit single-channel red, signed integer. 16 BPP. + R16U, //!< 16-bit single-channel red, unsigned integer. 16 BPP. + R16F, //!< 16-bit single-channel red, half-precision floating point. 16 BPP. + R16S, //!< 16-bit single-channel red, signed normalized. 16 BPP. + R32I, //!< 32-bit single-channel red, signed integer. 32 BPP. + R32U, //!< 32-bit single-channel red, unsigned integer. 32 BPP. + R32F, //!< 32-bit single-channel red, full-precision floating point. 32 BPP. + RG8, //!< Two 8-bit channels (red, green), unsigned normalized. 16 BPP. + RG8I, //!< Two 8-bit channels (red, green), signed integer. 16 BPP. + RG8U, //!< Two 8-bit channels (red, green), unsigned integer. 16 BPP. + RG8S, //!< Two 8-bit channels (red, green), signed normalized. 16 BPP. + RG16, //!< Two 16-bit channels (red, green), unsigned normalized. 32 BPP. + RG16I, //!< Two 16-bit channels (red, green), signed integer. 32 BPP. + RG16U, //!< Two 16-bit channels (red, green), unsigned integer. 32 BPP. + RG16F, //!< Two 16-bit channels (red, green), half-precision floating point. 32 BPP. + RG16S, //!< Two 16-bit channels (red, green), signed normalized. 32 BPP. + RG32I, //!< Two 32-bit channels (red, green), signed integer. 64 BPP. + RG32U, //!< Two 32-bit channels (red, green), unsigned integer. 64 BPP. + RG32F, //!< Two 32-bit channels (red, green), full-precision floating point. 64 BPP. + RGB8, //!< Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP. + RGB8I, //!< Three 8-bit channels (red, green, blue), signed integer. 24 BPP. + RGB8U, //!< Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP. + RGB8S, //!< Three 8-bit channels (red, green, blue), signed normalized. 24 BPP. + RGB9E5F, //!< Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP. + BGRA8, //!< Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP. + RGBA8, //!< Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP. + RGBA8I, //!< Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP. + RGBA8U, //!< Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP. + RGBA8S, //!< Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP. + RGBA16, //!< Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP. + RGBA16I, //!< Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP. + RGBA16U, //!< Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP. + RGBA16F, //!< Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP. + RGBA16S, //!< Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP. + RGBA32I, //!< Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP. + RGBA32U, //!< Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP. + RGBA32F, //!< Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP. + B5G6R5, //!< Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP. + R5G6B5, //!< Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP. + BGRA4, //!< Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP. + RGBA4, //!< Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP. + BGR5A1, //!< Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP. + RGB5A1, //!< Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP. + RGB10A2, //!< Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP. + 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, - D24, - D24S8, - D32, - D16F, - D24F, - D32F, - D0S8, + D16, //!< 16-bit depth, unsigned normalized. 16 BPP. + D24, //!< 24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP. + D24S8, //!< 24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP. + D32, //!< 32-bit depth, unsigned normalized. 32 BPP. + D16F, //!< 16-bit depth, floating point. 16 BPP. + D24F, //!< 24-bit depth, floating point (stored as 32-bit). 32 BPP. + D32F, //!< 32-bit depth, floating point. 32 BPP. + 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 - /// just swaps internal buffers, kicks render thread, and returns. In - /// singlethreaded renderer this call does frame rendering. + /// Advance to next frame. This is the main frame-advancement call on the + /// API thread (the thread from which `bgfx::init` was called). + /// + /// **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 - /// `bgfx::frame` to be called from API thread to process frame. - /// If timeout value is passed call will timeout and return even - /// if `bgfx::frame` is not called. + /// @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 be only used on platforms that don't - /// allow creating separate rendering thread. If it is called before - /// to bgfx::init, render thread won't be created by bgfx::init call. + /// @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`. /// /// @attention C99's equivalent binding is `bgfx_render_frame`. /// diff --git a/include/bgfx/c99/bgfx.h b/include/bgfx/c99/bgfx.h index b26b54013..d68eae935 100644 --- a/include/bgfx/c99/bgfx.h +++ b/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_BC2, /** ( 1) DXT3 R5G6B5A4 */ - BGFX_TEXTURE_FORMAT_BC3, /** ( 2) DXT5 R5G6B5A8 */ - BGFX_TEXTURE_FORMAT_BC4, /** ( 3) LATC1/ATI1 R8 */ - BGFX_TEXTURE_FORMAT_BC5, /** ( 4) LATC2/ATI2 RG8 */ - BGFX_TEXTURE_FORMAT_BC6H, /** ( 5) BC6H RGB16F */ - BGFX_TEXTURE_FORMAT_BC7, /** ( 6) BC7 RGB 4-7 bits per color channel, 0-8 bits alpha */ - BGFX_TEXTURE_FORMAT_ETC1, /** ( 7) ETC1 RGB8 */ - BGFX_TEXTURE_FORMAT_ETC2, /** ( 8) ETC2 RGB8 */ - BGFX_TEXTURE_FORMAT_ETC2A, /** ( 9) ETC2 RGBA8 */ - BGFX_TEXTURE_FORMAT_ETC2A1, /** (10) ETC2 RGB8A1 */ - BGFX_TEXTURE_FORMAT_EACR11, /** (11) EAC R11 UNORM */ - BGFX_TEXTURE_FORMAT_EACR11S, /** (12) EAC R11 SNORM */ - BGFX_TEXTURE_FORMAT_EACRG11, /** (13) EAC RG11 UNORM */ - BGFX_TEXTURE_FORMAT_EACRG11S, /** (14) EAC RG11 SNORM */ - BGFX_TEXTURE_FORMAT_PTC12, /** (15) PVRTC1 RGB 2BPP */ - BGFX_TEXTURE_FORMAT_PTC14, /** (16) PVRTC1 RGB 4BPP */ - BGFX_TEXTURE_FORMAT_PTC12A, /** (17) PVRTC1 RGBA 2BPP */ - BGFX_TEXTURE_FORMAT_PTC14A, /** (18) PVRTC1 RGBA 4BPP */ - BGFX_TEXTURE_FORMAT_PTC22, /** (19) PVRTC2 RGBA 2BPP */ - BGFX_TEXTURE_FORMAT_PTC24, /** (20) PVRTC2 RGBA 4BPP */ - BGFX_TEXTURE_FORMAT_ATC, /** (21) ATC RGB 4BPP */ - BGFX_TEXTURE_FORMAT_ATCE, /** (22) ATCE RGBA 8 BPP explicit alpha */ - BGFX_TEXTURE_FORMAT_ATCI, /** (23) ATCI RGBA 8 BPP interpolated alpha */ - BGFX_TEXTURE_FORMAT_ASTC4X4, /** (24) ASTC 4x4 8.0 BPP */ - BGFX_TEXTURE_FORMAT_ASTC5X4, /** (25) ASTC 5x4 6.40 BPP */ - BGFX_TEXTURE_FORMAT_ASTC5X5, /** (26) ASTC 5x5 5.12 BPP */ - BGFX_TEXTURE_FORMAT_ASTC6X5, /** (27) ASTC 6x5 4.27 BPP */ - BGFX_TEXTURE_FORMAT_ASTC6X6, /** (28) ASTC 6x6 3.56 BPP */ - BGFX_TEXTURE_FORMAT_ASTC8X5, /** (29) ASTC 8x5 3.20 BPP */ - BGFX_TEXTURE_FORMAT_ASTC8X6, /** (30) ASTC 8x6 2.67 BPP */ - BGFX_TEXTURE_FORMAT_ASTC8X8, /** (31) ASTC 8x8 2.00 BPP */ - BGFX_TEXTURE_FORMAT_ASTC10X5, /** (32) ASTC 10x5 2.56 BPP */ - BGFX_TEXTURE_FORMAT_ASTC10X6, /** (33) ASTC 10x6 2.13 BPP */ - BGFX_TEXTURE_FORMAT_ASTC10X8, /** (34) ASTC 10x8 1.60 BPP */ - BGFX_TEXTURE_FORMAT_ASTC10X10, /** (35) ASTC 10x10 1.28 BPP */ - BGFX_TEXTURE_FORMAT_ASTC12X10, /** (36) ASTC 12x10 1.07 BPP */ - BGFX_TEXTURE_FORMAT_ASTC12X12, /** (37) ASTC 12x12 0.89 BPP */ + 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) Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP. */ + 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) Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP. */ + BGFX_TEXTURE_FORMAT_BC5, /** ( 4) Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP. */ + BGFX_TEXTURE_FORMAT_BC6H, /** ( 5) Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP. */ + 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) Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP. */ + BGFX_TEXTURE_FORMAT_ETC2, /** ( 8) Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP. */ + BGFX_TEXTURE_FORMAT_ETC2A, /** ( 9) Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP. */ + BGFX_TEXTURE_FORMAT_ETC2A1, /** (10) Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP. */ + BGFX_TEXTURE_FORMAT_EACR11, /** (11) ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP. */ + BGFX_TEXTURE_FORMAT_EACR11S, /** (12) ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP. */ + BGFX_TEXTURE_FORMAT_EACRG11, /** (13) ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP. */ + BGFX_TEXTURE_FORMAT_EACRG11S, /** (14) ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP. */ + BGFX_TEXTURE_FORMAT_PTC12, /** (15) PowerVR Texture Compression v1. 3-channel RGB. 2 BPP. */ + BGFX_TEXTURE_FORMAT_PTC14, /** (16) PowerVR Texture Compression v1. 3-channel RGB. 4 BPP. */ + BGFX_TEXTURE_FORMAT_PTC12A, /** (17) PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP. */ + BGFX_TEXTURE_FORMAT_PTC14A, /** (18) PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP. */ + BGFX_TEXTURE_FORMAT_PTC22, /** (19) PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP. */ + BGFX_TEXTURE_FORMAT_PTC24, /** (20) PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP. */ + BGFX_TEXTURE_FORMAT_ATC, /** (21) AMD Texture Compression. 3-channel RGB. 4 BPP. */ + BGFX_TEXTURE_FORMAT_ATCE, /** (22) AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP. */ + BGFX_TEXTURE_FORMAT_ATCI, /** (23) AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC4X4, /** (24) Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC5X4, /** (25) Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC5X5, /** (26) Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC6X5, /** (27) Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC6X6, /** (28) Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC8X5, /** (29) Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC8X6, /** (30) Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC8X8, /** (31) Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC10X5, /** (32) Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC10X6, /** (33) Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC10X8, /** (34) Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC10X10, /** (35) Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP. */ + BGFX_TEXTURE_FORMAT_ASTC12X10, /** (36) Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 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_A8, /** (40) */ - BGFX_TEXTURE_FORMAT_R8, /** (41) */ - BGFX_TEXTURE_FORMAT_R8I, /** (42) */ - BGFX_TEXTURE_FORMAT_R8U, /** (43) */ - BGFX_TEXTURE_FORMAT_R8S, /** (44) */ - BGFX_TEXTURE_FORMAT_R16, /** (45) */ - BGFX_TEXTURE_FORMAT_R16I, /** (46) */ - BGFX_TEXTURE_FORMAT_R16U, /** (47) */ - BGFX_TEXTURE_FORMAT_R16F, /** (48) */ - BGFX_TEXTURE_FORMAT_R16S, /** (49) */ - BGFX_TEXTURE_FORMAT_R32I, /** (50) */ - BGFX_TEXTURE_FORMAT_R32U, /** (51) */ - BGFX_TEXTURE_FORMAT_R32F, /** (52) */ - BGFX_TEXTURE_FORMAT_RG8, /** (53) */ - BGFX_TEXTURE_FORMAT_RG8I, /** (54) */ - BGFX_TEXTURE_FORMAT_RG8U, /** (55) */ - BGFX_TEXTURE_FORMAT_RG8S, /** (56) */ - BGFX_TEXTURE_FORMAT_RG16, /** (57) */ - BGFX_TEXTURE_FORMAT_RG16I, /** (58) */ - BGFX_TEXTURE_FORMAT_RG16U, /** (59) */ - BGFX_TEXTURE_FORMAT_RG16F, /** (60) */ - BGFX_TEXTURE_FORMAT_RG16S, /** (61) */ - BGFX_TEXTURE_FORMAT_RG32I, /** (62) */ - BGFX_TEXTURE_FORMAT_RG32U, /** (63) */ - BGFX_TEXTURE_FORMAT_RG32F, /** (64) */ - BGFX_TEXTURE_FORMAT_RGB8, /** (65) */ - BGFX_TEXTURE_FORMAT_RGB8I, /** (66) */ - BGFX_TEXTURE_FORMAT_RGB8U, /** (67) */ - BGFX_TEXTURE_FORMAT_RGB8S, /** (68) */ - BGFX_TEXTURE_FORMAT_RGB9E5F, /** (69) */ - BGFX_TEXTURE_FORMAT_BGRA8, /** (70) */ - BGFX_TEXTURE_FORMAT_RGBA8, /** (71) */ - BGFX_TEXTURE_FORMAT_RGBA8I, /** (72) */ - BGFX_TEXTURE_FORMAT_RGBA8U, /** (73) */ - BGFX_TEXTURE_FORMAT_RGBA8S, /** (74) */ - BGFX_TEXTURE_FORMAT_RGBA16, /** (75) */ - BGFX_TEXTURE_FORMAT_RGBA16I, /** (76) */ - BGFX_TEXTURE_FORMAT_RGBA16U, /** (77) */ - BGFX_TEXTURE_FORMAT_RGBA16F, /** (78) */ - BGFX_TEXTURE_FORMAT_RGBA16S, /** (79) */ - BGFX_TEXTURE_FORMAT_RGBA32I, /** (80) */ - BGFX_TEXTURE_FORMAT_RGBA32U, /** (81) */ - BGFX_TEXTURE_FORMAT_RGBA32F, /** (82) */ - BGFX_TEXTURE_FORMAT_B5G6R5, /** (83) */ - BGFX_TEXTURE_FORMAT_R5G6B5, /** (84) */ - BGFX_TEXTURE_FORMAT_BGRA4, /** (85) */ - BGFX_TEXTURE_FORMAT_RGBA4, /** (86) */ - BGFX_TEXTURE_FORMAT_BGR5A1, /** (87) */ - BGFX_TEXTURE_FORMAT_RGB5A1, /** (88) */ - BGFX_TEXTURE_FORMAT_RGB10A2, /** (89) */ - BGFX_TEXTURE_FORMAT_RG11B10F, /** (90) */ + BGFX_TEXTURE_FORMAT_R1, /** (39) 1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP. */ + BGFX_TEXTURE_FORMAT_A8, /** (40) 8-bit single-channel alpha, unsigned normalized. 8 BPP. */ + BGFX_TEXTURE_FORMAT_R8, /** (41) 8-bit single-channel red, unsigned normalized. 8 BPP. */ + BGFX_TEXTURE_FORMAT_R8I, /** (42) 8-bit single-channel red, signed integer. 8 BPP. */ + BGFX_TEXTURE_FORMAT_R8U, /** (43) 8-bit single-channel red, unsigned integer. 8 BPP. */ + BGFX_TEXTURE_FORMAT_R8S, /** (44) 8-bit single-channel red, signed normalized. 8 BPP. */ + BGFX_TEXTURE_FORMAT_R16, /** (45) 16-bit single-channel red, unsigned normalized. 16 BPP. */ + BGFX_TEXTURE_FORMAT_R16I, /** (46) 16-bit single-channel red, signed integer. 16 BPP. */ + BGFX_TEXTURE_FORMAT_R16U, /** (47) 16-bit single-channel red, unsigned integer. 16 BPP. */ + BGFX_TEXTURE_FORMAT_R16F, /** (48) 16-bit single-channel red, half-precision floating point. 16 BPP. */ + BGFX_TEXTURE_FORMAT_R16S, /** (49) 16-bit single-channel red, signed normalized. 16 BPP. */ + BGFX_TEXTURE_FORMAT_R32I, /** (50) 32-bit single-channel red, signed integer. 32 BPP. */ + BGFX_TEXTURE_FORMAT_R32U, /** (51) 32-bit single-channel red, unsigned integer. 32 BPP. */ + BGFX_TEXTURE_FORMAT_R32F, /** (52) 32-bit single-channel red, full-precision floating point. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RG8, /** (53) Two 8-bit channels (red, green), unsigned normalized. 16 BPP. */ + BGFX_TEXTURE_FORMAT_RG8I, /** (54) Two 8-bit channels (red, green), signed integer. 16 BPP. */ + BGFX_TEXTURE_FORMAT_RG8U, /** (55) Two 8-bit channels (red, green), unsigned integer. 16 BPP. */ + BGFX_TEXTURE_FORMAT_RG8S, /** (56) Two 8-bit channels (red, green), signed normalized. 16 BPP. */ + BGFX_TEXTURE_FORMAT_RG16, /** (57) Two 16-bit channels (red, green), unsigned normalized. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RG16I, /** (58) Two 16-bit channels (red, green), signed integer. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RG16U, /** (59) Two 16-bit channels (red, green), unsigned integer. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RG16F, /** (60) Two 16-bit channels (red, green), half-precision floating point. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RG16S, /** (61) Two 16-bit channels (red, green), signed normalized. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RG32I, /** (62) Two 32-bit channels (red, green), signed integer. 64 BPP. */ + BGFX_TEXTURE_FORMAT_RG32U, /** (63) Two 32-bit channels (red, green), unsigned integer. 64 BPP. */ + BGFX_TEXTURE_FORMAT_RG32F, /** (64) Two 32-bit channels (red, green), full-precision floating point. 64 BPP. */ + BGFX_TEXTURE_FORMAT_RGB8, /** (65) Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP. */ + BGFX_TEXTURE_FORMAT_RGB8I, /** (66) Three 8-bit channels (red, green, blue), signed integer. 24 BPP. */ + BGFX_TEXTURE_FORMAT_RGB8U, /** (67) Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP. */ + BGFX_TEXTURE_FORMAT_RGB8S, /** (68) Three 8-bit channels (red, green, blue), signed normalized. 24 BPP. */ + 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) Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA8, /** (71) Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA8I, /** (72) Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA8U, /** (73) Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA8S, /** (74) Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA16, /** (75) Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA16I, /** (76) Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA16U, /** (77) Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA16F, /** (78) Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA16S, /** (79) Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA32I, /** (80) Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA32U, /** (81) Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP. */ + BGFX_TEXTURE_FORMAT_RGBA32F, /** (82) Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP. */ + 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) Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP. */ + 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) Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP. */ + 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) Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP. */ + 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) 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_D24, /** (93) */ - BGFX_TEXTURE_FORMAT_D24S8, /** (94) */ - BGFX_TEXTURE_FORMAT_D32, /** (95) */ - BGFX_TEXTURE_FORMAT_D16F, /** (96) */ - BGFX_TEXTURE_FORMAT_D24F, /** (97) */ - BGFX_TEXTURE_FORMAT_D32F, /** (98) */ - BGFX_TEXTURE_FORMAT_D0S8, /** (99) */ + BGFX_TEXTURE_FORMAT_D16, /** (92) 16-bit depth, unsigned normalized. 16 BPP. */ + 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) 24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP. */ + BGFX_TEXTURE_FORMAT_D32, /** (95) 32-bit depth, unsigned normalized. 32 BPP. */ + BGFX_TEXTURE_FORMAT_D16F, /** (96) 16-bit depth, floating point. 16 BPP. */ + BGFX_TEXTURE_FORMAT_D24F, /** (97) 24-bit depth, floating point (stored as 32-bit). 32 BPP. */ + BGFX_TEXTURE_FORMAT_D32F, /** (98) 32-bit depth, floating point. 32 BPP. */ + 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 - * just swaps internal buffers, kicks render thread, and returns. In - * singlethreaded renderer this call does frame rendering. + * Advance to next frame. This is the main frame-advancement call on the + * API thread (the thread from which `bgfx::init` was called). + * + * **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 - * `bgfx::frame` to be called from API thread to process frame. - * If timeout value is passed call will timeout and return even - * if `bgfx::frame` is not called. + * 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: * - * @warning This call should be only used on platforms that don't - * allow creating separate rendering thread. If it is called before - * to bgfx::init, render thread won't be created by bgfx::init call. + * 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. + * + * @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. * diff --git a/scripts/bgfx.idl b/scripts/bgfx.idl index a2a6e0a07..5350e27d5 100644 --- a/scripts/bgfx.idl +++ b/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 - .BC2 --- DXT3 R5G6B5A4 - .BC3 --- DXT5 R5G6B5A8 - .BC4 --- LATC1/ATI1 R8 - .BC5 --- LATC2/ATI2 RG8 - .BC6H --- BC6H RGB16F - .BC7 --- BC7 RGB 4-7 bits per color channel, 0-8 bits alpha - .ETC1 --- ETC1 RGB8 - .ETC2 --- ETC2 RGB8 - .ETC2A --- ETC2 RGBA8 - .ETC2A1 --- ETC2 RGB8A1 - .EACR11 --- EAC R11 UNORM - .EACR11S --- EAC R11 SNORM - .EACRG11 --- EAC RG11 UNORM - .EACRG11S --- EAC RG11 SNORM - .PTC12 --- PVRTC1 RGB 2BPP - .PTC14 --- PVRTC1 RGB 4BPP - .PTC12A --- PVRTC1 RGBA 2BPP - .PTC14A --- PVRTC1 RGBA 4BPP - .PTC22 --- PVRTC2 RGBA 2BPP - .PTC24 --- PVRTC2 RGBA 4BPP - .ATC --- ATC RGB 4BPP - .ATCE --- ATCE RGBA 8 BPP explicit alpha - .ATCI --- ATCI RGBA 8 BPP interpolated alpha - .ASTC4x4 --- ASTC 4x4 8.0 BPP - .ASTC5x4 --- ASTC 5x4 6.40 BPP - .ASTC5x5 --- ASTC 5x5 5.12 BPP - .ASTC6x5 --- ASTC 6x5 4.27 BPP - .ASTC6x6 --- ASTC 6x6 3.56 BPP - .ASTC8x5 --- ASTC 8x5 3.20 BPP - .ASTC8x6 --- ASTC 8x6 2.67 BPP - .ASTC8x8 --- ASTC 8x8 2.00 BPP - .ASTC10x5 --- ASTC 10x5 2.56 BPP - .ASTC10x6 --- ASTC 10x6 2.13 BPP - .ASTC10x8 --- ASTC 10x8 1.60 BPP - .ASTC10x10 --- ASTC 10x10 1.28 BPP - .ASTC12x10 --- ASTC 12x10 1.07 BPP - .ASTC12x12 --- ASTC 12x12 0.89 BPP - .Unknown --- Compressed formats above. - .R1 - .A8 - .R8 - .R8I - .R8U - .R8S - .R16 - .R16I - .R16U - .R16F - .R16S - .R32I - .R32U - .R32F - .RG8 - .RG8I - .RG8U - .RG8S - .RG16 - .RG16I - .RG16U - .RG16F - .RG16S - .RG32I - .RG32U - .RG32F - .RGB8 - .RGB8I - .RGB8U - .RGB8S - .RGB9E5F - .BGRA8 - .RGBA8 - .RGBA8I - .RGBA8U - .RGBA8S - .RGBA16 - .RGBA16I - .RGBA16U - .RGBA16F - .RGBA16S - .RGBA32I - .RGBA32U - .RGBA32F - .B5G6R5 - .R5G6B5 - .BGRA4 - .RGBA4 - .BGR5A1 - .RGB5A1 - .RGB10A2 - .RG11B10F + .BC1 --- Block Compression 1. 5-bit R, 6-bit G, 5-bit B, 1-bit A. 4 BPP. + .BC2 --- Block Compression 2. 5-bit R, 6-bit G, 5-bit B, 4-bit explicit A. 8 BPP. + .BC3 --- Block Compression 3. 5-bit R, 6-bit G, 5-bit B, 8-bit interpolated A. 8 BPP. + .BC4 --- Block Compression 4. Single 8-bit red channel, unsigned normalized. 4 BPP. + .BC5 --- Block Compression 5. Two 8-bit channels (RG), unsigned normalized. 8 BPP. + .BC6H --- Block Compression 6H. Three 16-bit floating-point channels (RGB), HDR. 8 BPP. + .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 --- Ericsson Texture Compression 1. 8-bit per channel RGB. 4 BPP. + .ETC2 --- Ericsson Texture Compression 2. 8-bit per channel RGB. 4 BPP. + .ETC2A --- Ericsson Texture Compression 2 with full alpha. 8-bit per channel RGBA. 8 BPP. + .ETC2A1 --- Ericsson Texture Compression 2 with 1-bit punch-through alpha. 4 BPP. + .EACR11 --- ETC2 Alpha Compression, single 11-bit red channel, unsigned normalized. 4 BPP. + .EACR11S --- ETC2 Alpha Compression, single 11-bit red channel, signed normalized. 4 BPP. + .EACRG11 --- ETC2 Alpha Compression, two 11-bit channels (RG), unsigned normalized. 8 BPP. + .EACRG11S --- ETC2 Alpha Compression, two 11-bit channels (RG), signed normalized. 8 BPP. + .PTC12 --- PowerVR Texture Compression v1. 3-channel RGB. 2 BPP. + .PTC14 --- PowerVR Texture Compression v1. 3-channel RGB. 4 BPP. + .PTC12A --- PowerVR Texture Compression v1. 4-channel RGBA. 2 BPP. + .PTC14A --- PowerVR Texture Compression v1. 4-channel RGBA. 4 BPP. + .PTC22 --- PowerVR Texture Compression v2. 4-channel RGBA. 2 BPP. + .PTC24 --- PowerVR Texture Compression v2. 4-channel RGBA. 4 BPP. + .ATC --- AMD Texture Compression. 3-channel RGB. 4 BPP. + .ATCE --- AMD Texture Compression with explicit alpha. 4-channel RGBA. 8 BPP. + .ATCI --- AMD Texture Compression with interpolated alpha. 4-channel RGBA. 8 BPP. + .ASTC4x4 --- Adaptive Scalable Texture Compression, 4x4 block, RGBA. 8.00 BPP. + .ASTC5x4 --- Adaptive Scalable Texture Compression, 5x4 block, RGBA. 6.40 BPP. + .ASTC5x5 --- Adaptive Scalable Texture Compression, 5x5 block, RGBA. 5.12 BPP. + .ASTC6x5 --- Adaptive Scalable Texture Compression, 6x5 block, RGBA. 4.27 BPP. + .ASTC6x6 --- Adaptive Scalable Texture Compression, 6x6 block, RGBA. 3.56 BPP. + .ASTC8x5 --- Adaptive Scalable Texture Compression, 8x5 block, RGBA. 3.20 BPP. + .ASTC8x6 --- Adaptive Scalable Texture Compression, 8x6 block, RGBA. 2.67 BPP. + .ASTC8x8 --- Adaptive Scalable Texture Compression, 8x8 block, RGBA. 2.00 BPP. + .ASTC10x5 --- Adaptive Scalable Texture Compression, 10x5 block, RGBA. 2.56 BPP. + .ASTC10x6 --- Adaptive Scalable Texture Compression, 10x6 block, RGBA. 2.13 BPP. + .ASTC10x8 --- Adaptive Scalable Texture Compression, 10x8 block, RGBA. 1.60 BPP. + .ASTC10x10 --- Adaptive Scalable Texture Compression, 10x10 block, RGBA. 1.28 BPP. + .ASTC12x10 --- Adaptive Scalable Texture Compression, 12x10 block, RGBA. 1.07 BPP. + .ASTC12x12 --- Adaptive Scalable Texture Compression, 12x12 block, RGBA. 0.89 BPP. + .Unknown --- Compressed formats above. + .R1 --- 1-bit single-channel red. Monochrome, 1-bit per pixel. 1 BPP. + .A8 --- 8-bit single-channel alpha, unsigned normalized. 8 BPP. + .R8 --- 8-bit single-channel red, unsigned normalized. 8 BPP. + .R8I --- 8-bit single-channel red, signed integer. 8 BPP. + .R8U --- 8-bit single-channel red, unsigned integer. 8 BPP. + .R8S --- 8-bit single-channel red, signed normalized. 8 BPP. + .R16 --- 16-bit single-channel red, unsigned normalized. 16 BPP. + .R16I --- 16-bit single-channel red, signed integer. 16 BPP. + .R16U --- 16-bit single-channel red, unsigned integer. 16 BPP. + .R16F --- 16-bit single-channel red, half-precision floating point. 16 BPP. + .R16S --- 16-bit single-channel red, signed normalized. 16 BPP. + .R32I --- 32-bit single-channel red, signed integer. 32 BPP. + .R32U --- 32-bit single-channel red, unsigned integer. 32 BPP. + .R32F --- 32-bit single-channel red, full-precision floating point. 32 BPP. + .RG8 --- Two 8-bit channels (red, green), unsigned normalized. 16 BPP. + .RG8I --- Two 8-bit channels (red, green), signed integer. 16 BPP. + .RG8U --- Two 8-bit channels (red, green), unsigned integer. 16 BPP. + .RG8S --- Two 8-bit channels (red, green), signed normalized. 16 BPP. + .RG16 --- Two 16-bit channels (red, green), unsigned normalized. 32 BPP. + .RG16I --- Two 16-bit channels (red, green), signed integer. 32 BPP. + .RG16U --- Two 16-bit channels (red, green), unsigned integer. 32 BPP. + .RG16F --- Two 16-bit channels (red, green), half-precision floating point. 32 BPP. + .RG16S --- Two 16-bit channels (red, green), signed normalized. 32 BPP. + .RG32I --- Two 32-bit channels (red, green), signed integer. 64 BPP. + .RG32U --- Two 32-bit channels (red, green), unsigned integer. 64 BPP. + .RG32F --- Two 32-bit channels (red, green), full-precision floating point. 64 BPP. + .RGB8 --- Three 8-bit channels (red, green, blue), unsigned normalized. 24 BPP. + .RGB8I --- Three 8-bit channels (red, green, blue), signed integer. 24 BPP. + .RGB8U --- Three 8-bit channels (red, green, blue), unsigned integer. 24 BPP. + .RGB8S --- Three 8-bit channels (red, green, blue), signed normalized. 24 BPP. + .RGB9E5F --- Shared-exponent RGB. 9 bits per RGB channel with a shared 5-bit exponent, floating point. 32 BPP. + .BGRA8 --- Four 8-bit channels (blue, green, red, alpha), unsigned normalized. BGRA byte order. 32 BPP. + .RGBA8 --- Four 8-bit channels (red, green, blue, alpha), unsigned normalized. 32 BPP. + .RGBA8I --- Four 8-bit channels (red, green, blue, alpha), signed integer. 32 BPP. + .RGBA8U --- Four 8-bit channels (red, green, blue, alpha), unsigned integer. 32 BPP. + .RGBA8S --- Four 8-bit channels (red, green, blue, alpha), signed normalized. 32 BPP. + .RGBA16 --- Four 16-bit channels (red, green, blue, alpha), unsigned normalized. 64 BPP. + .RGBA16I --- Four 16-bit channels (red, green, blue, alpha), signed integer. 64 BPP. + .RGBA16U --- Four 16-bit channels (red, green, blue, alpha), unsigned integer. 64 BPP. + .RGBA16F --- Four 16-bit channels (red, green, blue, alpha), half-precision floating point. 64 BPP. + .RGBA16S --- Four 16-bit channels (red, green, blue, alpha), signed normalized. 64 BPP. + .RGBA32I --- Four 32-bit channels (red, green, blue, alpha), signed integer. 128 BPP. + .RGBA32U --- Four 32-bit channels (red, green, blue, alpha), unsigned integer. 128 BPP. + .RGBA32F --- Four 32-bit channels (red, green, blue, alpha), full-precision floating point. 128 BPP. + .B5G6R5 --- Packed 16-bit, 5-bit blue, 6-bit green, 5-bit red. BGR byte order, unsigned normalized. 16 BPP. + .R5G6B5 --- Packed 16-bit, 5-bit red, 6-bit green, 5-bit blue. RGB byte order, unsigned normalized. 16 BPP. + .BGRA4 --- Packed 16-bit, 4-bit per channel (blue, green, red, alpha). BGRA byte order, unsigned normalized. 16 BPP. + .RGBA4 --- Packed 16-bit, 4-bit per channel (red, green, blue, alpha), unsigned normalized. 16 BPP. + .BGR5A1 --- Packed 16-bit, 5-bit blue, 5-bit green, 5-bit red, 1-bit alpha. BGRA byte order, unsigned normalized. 16 BPP. + .RGB5A1 --- Packed 16-bit, 5-bit red, 5-bit green, 5-bit blue, 1-bit alpha, unsigned normalized. 16 BPP. + .RGB10A2 --- Packed 32-bit, 10-bit red, 10-bit green, 10-bit blue, 2-bit alpha, unsigned normalized. 32 BPP. + .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 - .D24 - .D24S8 - .D32 - .D16F - .D24F - .D32F - .D0S8 + .D16 --- 16-bit depth, unsigned normalized. 16 BPP. + .D24 --- 24-bit depth, unsigned normalized (stored as 32-bit with 8 bits unused). 32 BPP. + .D24S8 --- 24-bit depth, unsigned normalized, with 8-bit stencil. 32 BPP. + .D32 --- 32-bit depth, unsigned normalized. 32 BPP. + .D16F --- 16-bit depth, floating point. 16 BPP. + .D24F --- 24-bit depth, floating point (stored as 32-bit). 32 BPP. + .D32F --- 32-bit depth, floating point. 32 BPP. + .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 ---- just swaps internal buffers, kicks render thread, and returns. In ---- singlethreaded renderer this call does frame rendering. +--- Advance to next frame. This is the main frame-advancement call on the +--- API thread (the thread from which `bgfx::init` was called). +--- +--- **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 ---- `bgfx::frame` to be called from API thread to process frame. ---- If timeout value is passed call will timeout and return even ---- if `bgfx::frame` is not called. +--- 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: --- ---- @warning This call should be only used on platforms that don't ---- allow creating separate rendering thread. If it is called before ---- to bgfx::init, render thread won't be created by bgfx::init call. +--- 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. +--- +--- @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`. diff --git a/scripts/docs-rst.lua b/scripts/docs-rst.lua index 2a03d65a3..255cf5c49 100644 --- a/scripts/docs-rst.lua +++ b/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). diff --git a/src/config.h b/src/config.h index a2f14e221..8a110672f 100644 --- a/src/config.h +++ b/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<