Scarfski/bgfx
1
0
Fork 0
mirror of https://github.com/bkaradzic/bgfx.git synced 2026-06-08 03:13:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improved docs on bgfx::begin/end. (#3621)

Browse Source
This commit is contained in:
Branimir Karadžić
2026-03-05 21:37:34 -08:00
committed by GitHub
parent 8e68ab9a83
commit 298f5b0202
9 changed files with 333 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
bindings/bf/bgfx.bf
View File

@@ -4135,16 +4135,53 @@ public static class bgfx
public static extern void reset_view(ViewId _id);
/// <summary>
/// Begin submitting draw calls from thread.
/// Begin submitting draw calls from thread. Obtains an encoder that can be
/// used to submit draw calls, compute dispatches, and state changes.
///
/// In multithreaded mode (`BGFX_CONFIG_MULTITHREADED=1`), multiple threads
/// can each obtain their own encoder and submit draw calls in parallel.
/// Each encoder writes into its own uniform buffer, so there is no
/// contention between threads. The maximum number of simultaneous encoders
/// is configured via `Limits.maxEncoders` in `bgfx::Init` (default: 8).
///
/// When called from the API thread (the thread that called `bgfx::init`)
/// with `_forceNewEncoder` set to `false`, the default internal encoder
/// (encoder 0) is returned. This is the same encoder used by the legacy
/// non-encoder API (`bgfx::setState`, `bgfx::submit`, etc.). When called
/// from a worker thread (or with `_forceNewEncoder` set to `true`), a new
/// encoder is allocated from the encoder pool.
///
/// @remarks
/// The returned `Encoder` pointer is valid until `bgfx::end` is called
/// with it. All encoders must be ended before `bgfx::frame` is called.
/// If `bgfx::frame` is called while encoders are still active, it will
/// wait for them to finish. Returns `NULL` if no encoder slots are
/// available (all `maxEncoders` slots are in use).
/// See also: `bgfx::end`, `bgfx::frame`.
///
/// </summary>
///
/// <param name="_forThread">Explicitly request an encoder for a worker thread.</param>
/// <param name="_forceNewEncoder">Force allocation of a new encoder from the pool, even when called from the API thread.</param>
///
[LinkName("bgfx_encoder_begin")]
public static extern Encoder* encoder_begin(bool _forThread);
public static extern Encoder* encoder_begin(bool _forceNewEncoder);
/// <summary>
/// End submitting draw calls from thread.
/// End submitting draw calls from thread. Returns the encoder obtained from
/// `bgfx::begin` back to the encoder pool.
///
/// After this call the `Encoder` pointer is no longer valid and must not
/// be used. The encoder's recorded draw calls and state changes are finalized
/// and will be included in the next frame when `bgfx::frame` is called.
///
/// @remarks
/// Must be called from the same thread that called `bgfx::begin` for
/// this encoder. All encoders must be ended before `bgfx::frame` is
/// called. The default encoder (encoder 0, used by the legacy API) is
/// managed internally and does not need to be passed to `bgfx::end`;
/// passing it is harmless but has no effect.
/// See also: `bgfx::begin`, `bgfx::frame`.
///
/// </summary>
///
/// <param name="_encoder">Encoder.</param>

45
bindings/c3/bgfx.c3
View File

@@ -2889,11 +2889,48 @@ extern fn void set_view_shading_rate(ushort _id, ShadingRate _shadingRate) @exte
// _id : `_id View id.`
extern fn void reset_view(ushort _id) @extern("bgfx_reset_view");
// Begin submitting draw calls from thread.
// _forThread : `Explicitly request an encoder for a worker thread.`
extern fn Encoder* encoder_begin(bool _forThread) @extern("bgfx_encoder_begin");
// Begin submitting draw calls from thread. Obtains an encoder that can be
// used to submit draw calls, compute dispatches, and state changes.
//
// In multithreaded mode (`BGFX_CONFIG_MULTITHREADED=1`), multiple threads
// can each obtain their own encoder and submit draw calls in parallel.
// Each encoder writes into its own uniform buffer, so there is no
// contention between threads. The maximum number of simultaneous encoders
// is configured via `Limits.maxEncoders` in `bgfx::Init` (default: 8).
//
// When called from the API thread (the thread that called `bgfx::init`)
// with `_forceNewEncoder` set to `false`, the default internal encoder
// (encoder 0) is returned. This is the same encoder used by the legacy
// non-encoder API (`bgfx::setState`, `bgfx::submit`, etc.). When called
// from a worker thread (or with `_forceNewEncoder` set to `true`), a new
// encoder is allocated from the encoder pool.
//
// @remarks
// The returned `Encoder` pointer is valid until `bgfx::end` is called
// with it. All encoders must be ended before `bgfx::frame` is called.
// If `bgfx::frame` is called while encoders are still active, it will
// wait for them to finish. Returns `NULL` if no encoder slots are
// available (all `maxEncoders` slots are in use).
// See also: `bgfx::end`, `bgfx::frame`.
//
// _forceNewEncoder : `Force allocation of a new encoder from the pool, even when called from the API thread.`
extern fn Encoder* encoder_begin(bool _forceNewEncoder) @extern("bgfx_encoder_begin");
// End submitting draw calls from thread.
// End submitting draw calls from thread. Returns the encoder obtained from
// `bgfx::begin` back to the encoder pool.
//
// After this call the `Encoder` pointer is no longer valid and must not
// be used. The encoder's recorded draw calls and state changes are finalized
// and will be included in the next frame when `bgfx::frame` is called.
//
// @remarks
// Must be called from the same thread that called `bgfx::begin` for
// this encoder. All encoders must be ended before `bgfx::frame` is
// called. The default encoder (encoder 0, used by the legacy API) is
// managed internally and does not need to be passed to `bgfx::end`;
// passing it is harmless but has no effect.
// See also: `bgfx::begin`, `bgfx::frame`.
//
// _encoder : `Encoder.`
extern fn void encoder_end(Encoder* _encoder) @extern("bgfx_encoder_end");

45
bindings/cs/bgfx.cs
View File

@@ -4088,16 +4088,53 @@ public static partial class bgfx
public static extern unsafe void reset_view(ushort _id);
/// <summary>
/// Begin submitting draw calls from thread.
/// Begin submitting draw calls from thread. Obtains an encoder that can be
/// used to submit draw calls, compute dispatches, and state changes.
///
/// In multithreaded mode (`BGFX_CONFIG_MULTITHREADED=1`), multiple threads
/// can each obtain their own encoder and submit draw calls in parallel.
/// Each encoder writes into its own uniform buffer, so there is no
/// contention between threads. The maximum number of simultaneous encoders
/// is configured via `Limits.maxEncoders` in `bgfx::Init` (default: 8).
///
/// When called from the API thread (the thread that called `bgfx::init`)
/// with `_forceNewEncoder` set to `false`, the default internal encoder
/// (encoder 0) is returned. This is the same encoder used by the legacy
/// non-encoder API (`bgfx::setState`, `bgfx::submit`, etc.). When called
/// from a worker thread (or with `_forceNewEncoder` set to `true`), a new
/// encoder is allocated from the encoder pool.
///
/// @remarks
/// The returned `Encoder` pointer is valid until `bgfx::end` is called
/// with it. All encoders must be ended before `bgfx::frame` is called.
/// If `bgfx::frame` is called while encoders are still active, it will
/// wait for them to finish. Returns `NULL` if no encoder slots are
/// available (all `maxEncoders` slots are in use).
/// See also: `bgfx::end`, `bgfx::frame`.
///
/// </summary>
///
/// <param name="_forThread">Explicitly request an encoder for a worker thread.</param>
/// <param name="_forceNewEncoder">Force allocation of a new encoder from the pool, even when called from the API thread.</param>
///
[DllImport(DllName, EntryPoint="bgfx_encoder_begin", CallingConvention = CallingConvention.Cdecl)]
public static extern unsafe Encoder* encoder_begin(bool _forThread);
public static extern unsafe Encoder* encoder_begin(bool _forceNewEncoder);
/// <summary>
/// End submitting draw calls from thread.
/// End submitting draw calls from thread. Returns the encoder obtained from
/// `bgfx::begin` back to the encoder pool.
///
/// After this call the `Encoder` pointer is no longer valid and must not
/// be used. The encoder's recorded draw calls and state changes are finalized
/// and will be included in the next frame when `bgfx::frame` is called.
///
/// @remarks
/// Must be called from the same thread that called `bgfx::begin` for
/// this encoder. All encoders must be ended before `bgfx::frame` is
/// called. The default encoder (encoder 0, used by the legacy API) is
/// managed internally and does not need to be passed to `bgfx::end`;
/// passing it is harmless but has no effect.
/// See also: `bgfx::begin`, `bgfx::frame`.
///
/// </summary>
///
/// <param name="_encoder">Encoder.</param>

46
bindings/d/package.d
View File

@@ -3231,14 +3231,52 @@ mixin(joinFnBinds((){
{q{void}, q{resetView}, q{ViewID id}, ext: `C++, "bgfx"`},
/**
* Begin submitting draw calls from thread.
* Begin submitting draw calls from thread. Obtains an encoder that can be
* used to submit draw calls, compute dispatches, and state changes.
*
* In multithreaded mode (`BGFX_CONFIG_MULTITHREADED=1`), multiple threads
* can each obtain their own encoder and submit draw calls in parallel.
* Each encoder writes into its own uniform buffer, so there is no
* contention between threads. The maximum number of simultaneous encoders
* is configured via `Limits.maxEncoders` in `bgfx::Init` (default: 8).
*
* When called from the API thread (the thread that called `bgfx::init`)
* with `_forceNewEncoder` set to `false`, the default internal encoder
* (encoder 0) is returned. This is the same encoder used by the legacy
* non-encoder API (`bgfx::setState`, `bgfx::submit`, etc.). When called
* from a worker thread (or with `_forceNewEncoder` set to `true`), a new
* encoder is allocated from the encoder pool.
*
* Remarks:
* The returned `Encoder` pointer is valid until `bgfx::end` is called
* with it. All encoders must be ended before `bgfx::frame` is called.
* If `bgfx::frame` is called while encoders are still active, it will
* wait for them to finish. Returns `NULL` if no encoder slots are
* available (all `maxEncoders` slots are in use).
* See also: `bgfx::end`, `bgfx::frame`.
*
Params:
forThread = Explicitly request an encoder for a worker thread.
forceNewEncoder = Force allocation of a new encoder from the pool,
even when called from the API thread.
*/
{q{Encoder*}, q{begin}, q{bool forThread=false}, ext: `C++, "bgfx"`},
{q{Encoder*}, q{begin}, q{bool forceNewEncoder=false}, ext: `C++, "bgfx"`},
/**
* End submitting draw calls from thread.
* End submitting draw calls from thread. Returns the encoder obtained from
* `bgfx::begin` back to the encoder pool.
*
* After this call the `Encoder` pointer is no longer valid and must not
* be used. The encoder's recorded draw calls and state changes are finalized
* and will be included in the next frame when `bgfx::frame` is called.
*
* Remarks:
* Must be called from the same thread that called `bgfx::begin` for
* this encoder. All encoders must be ended before `bgfx::frame` is
* called. The default encoder (encoder 0, used by the legacy API) is
* managed internally and does not need to be passed to `bgfx::end`;
* passing it is harmless but has no effect.
* See also: `bgfx::begin`, `bgfx::frame`.
*
Params:
encoder = Encoder.
*/

49
bindings/zig/bgfx.zig
View File

@@ -3281,14 +3281,51 @@ pub inline fn resetView(_id: ViewId) void {
}
extern fn bgfx_reset_view(_id: ViewId) void;
/// Begin submitting draw calls from thread.
/// <param name="_forThread">Explicitly request an encoder for a worker thread.</param>
pub inline fn encoderBegin(_forThread: bool) ?*Encoder {
return bgfx_encoder_begin(_forThread);
/// Begin submitting draw calls from thread. Obtains an encoder that can be
/// used to submit draw calls, compute dispatches, and state changes.
///
/// In multithreaded mode (`BGFX_CONFIG_MULTITHREADED=1`), multiple threads
/// can each obtain their own encoder and submit draw calls in parallel.
/// Each encoder writes into its own uniform buffer, so there is no
/// contention between threads. The maximum number of simultaneous encoders
/// is configured via `Limits.maxEncoders` in `bgfx::Init` (default: 8).
///
/// When called from the API thread (the thread that called `bgfx::init`)
/// with `_forceNewEncoder` set to `false`, the default internal encoder
/// (encoder 0) is returned. This is the same encoder used by the legacy
/// non-encoder API (`bgfx::setState`, `bgfx::submit`, etc.). When called
/// from a worker thread (or with `_forceNewEncoder` set to `true`), a new
/// encoder is allocated from the encoder pool.
///
/// @remarks
/// The returned `Encoder` pointer is valid until `bgfx::end` is called
/// with it. All encoders must be ended before `bgfx::frame` is called.
/// If `bgfx::frame` is called while encoders are still active, it will
/// wait for them to finish. Returns `NULL` if no encoder slots are
/// available (all `maxEncoders` slots are in use).
/// See also: `bgfx::end`, `bgfx::frame`.
///
/// <param name="_forceNewEncoder">Force allocation of a new encoder from the pool, even when called from the API thread.</param>
pub inline fn encoderBegin(_forceNewEncoder: bool) ?*Encoder {
return bgfx_encoder_begin(_forceNewEncoder);
}
extern fn bgfx_encoder_begin(_forThread: bool) ?*Encoder;
extern fn bgfx_encoder_begin(_forceNewEncoder: bool) ?*Encoder;
/// End submitting draw calls from thread.
/// End submitting draw calls from thread. Returns the encoder obtained from
/// `bgfx::begin` back to the encoder pool.
///
/// After this call the `Encoder` pointer is no longer valid and must not
/// be used. The encoder's recorded draw calls and state changes are finalized
/// and will be included in the next frame when `bgfx::frame` is called.
///
/// @remarks
/// Must be called from the same thread that called `bgfx::begin` for
/// this encoder. All encoders must be ended before `bgfx::frame` is
/// called. The default encoder (encoder 0, used by the legacy API) is
/// managed internally and does not need to be passed to `bgfx::end`;
/// passing it is harmless but has no effect.
/// See also: `bgfx::begin`, `bgfx::frame`.
///
/// <param name="_encoder">Encoder.</param>
pub inline fn encoderEnd(_encoder: ?*Encoder) void {
return bgfx_encoder_end(_encoder);

44
include/bgfx/bgfx.h
View File

@@ -3735,20 +3735,56 @@ namespace bgfx
///
void resetView(ViewId _id);
/// Begin submitting draw calls from thread.
/// Begin submitting draw calls from thread. Obtains an encoder that can be
/// used to submit draw calls, compute dispatches, and state changes.
///
/// @param[in] _forThread Explicitly request an encoder for a worker thread.
/// In multithreaded mode (`BGFX_CONFIG_MULTITHREADED=1`), multiple threads
/// can each obtain their own encoder and submit draw calls in parallel.
/// Each encoder writes into its own uniform buffer, so there is no
/// contention between threads. The maximum number of simultaneous encoders
/// is configured via `Limits.maxEncoders` in `bgfx::Init` (default: 8).
///
/// When called from the API thread (the thread that called `bgfx::init`)
/// with `_forceNewEncoder` set to `false`, the default internal encoder
/// (encoder 0) is returned. This is the same encoder used by the legacy
/// non-encoder API (`bgfx::setState`, `bgfx::submit`, etc.). When called
/// from a worker thread (or with `_forceNewEncoder` set to `true`), a new
/// encoder is allocated from the encoder pool.
///
/// @param[in] _forceNewEncoder Force allocation of a new encoder from the pool,
/// even when called from the API thread.
///
/// @returns Encoder.
///
/// @remarks
/// The returned `Encoder` pointer is valid until `bgfx::end` is called
/// with it. All encoders must be ended before `bgfx::frame` is called.
/// If `bgfx::frame` is called while encoders are still active, it will
/// wait for them to finish. Returns `NULL` if no encoder slots are
/// available (all `maxEncoders` slots are in use).
/// See also: `bgfx::end`, `bgfx::frame`.
///
/// @attention C99's equivalent binding is `bgfx_encoder_begin`.
///
Encoder* begin(bool _forThread = false);
Encoder* begin(bool _forceNewEncoder = false);
/// End submitting draw calls from thread.
/// End submitting draw calls from thread. Returns the encoder obtained from
/// `bgfx::begin` back to the encoder pool.
///
/// After this call the `Encoder` pointer is no longer valid and must not
/// be used. The encoder's recorded draw calls and state changes are finalized
/// and will be included in the next frame when `bgfx::frame` is called.
///
/// @param[in] _encoder Encoder.
///
/// @remarks
/// Must be called from the same thread that called `bgfx::begin` for
/// this encoder. All encoders must be ended before `bgfx::frame` is
/// called. The default encoder (encoder 0, used by the legacy API) is
/// managed internally and does not need to be passed to `bgfx::end`;
/// passing it is harmless but has no effect.
/// See also: `bgfx::begin`, `bgfx::frame`.
///
/// @attention C99's equivalent binding is `bgfx_encoder_end`.
///
void end(Encoder* _encoder);

46
include/bgfx/c99/bgfx.h
View File

@@ -2544,17 +2544,53 @@ BGFX_C_API void bgfx_set_view_shading_rate(bgfx_view_id_t _id, bgfx_shading_rate
BGFX_C_API void bgfx_reset_view(bgfx_view_id_t _id);
/**
* Begin submitting draw calls from thread.
* Begin submitting draw calls from thread. Obtains an encoder that can be
* used to submit draw calls, compute dispatches, and state changes.
*
* @param[in] _forThread Explicitly request an encoder for a worker thread.
* In multithreaded mode (`BGFX_CONFIG_MULTITHREADED=1`), multiple threads
* can each obtain their own encoder and submit draw calls in parallel.
* Each encoder writes into its own uniform buffer, so there is no
* contention between threads. The maximum number of simultaneous encoders
* is configured via `Limits.maxEncoders` in `bgfx::Init` (default: 8).
*
* When called from the API thread (the thread that called `bgfx::init`)
* with `_forceNewEncoder` set to `false`, the default internal encoder
* (encoder 0) is returned. This is the same encoder used by the legacy
* non-encoder API (`bgfx::setState`, `bgfx::submit`, etc.). When called
* from a worker thread (or with `_forceNewEncoder` set to `true`), a new
* encoder is allocated from the encoder pool.
*
* @remarks
* The returned `Encoder` pointer is valid until `bgfx::end` is called
* with it. All encoders must be ended before `bgfx::frame` is called.
* If `bgfx::frame` is called while encoders are still active, it will
* wait for them to finish. Returns `NULL` if no encoder slots are
* available (all `maxEncoders` slots are in use).
* See also: `bgfx::end`, `bgfx::frame`.
*
* @param[in] _forceNewEncoder Force allocation of a new encoder from the pool,
* even when called from the API thread.
*
* @returns Encoder.
*
*/
BGFX_C_API bgfx_encoder_t* bgfx_encoder_begin(bool _forThread);
BGFX_C_API bgfx_encoder_t* bgfx_encoder_begin(bool _forceNewEncoder);
/**
* End submitting draw calls from thread.
* End submitting draw calls from thread. Returns the encoder obtained from
* `bgfx::begin` back to the encoder pool.
*
* After this call the `Encoder` pointer is no longer valid and must not
* be used. The encoder's recorded draw calls and state changes are finalized
* and will be included in the next frame when `bgfx::frame` is called.
*
* @remarks
* Must be called from the same thread that called `bgfx::begin` for
* this encoder. All encoders must be ended before `bgfx::frame` is
* called. The default encoder (encoder 0, used by the legacy API) is
* managed internally and does not need to be passed to `bgfx::end`;
* passing it is harmless but has no effect.
* See also: `bgfx::begin`, `bgfx::frame`.
*
* @param[in] _encoder Encoder.
*
@@ -4049,7 +4085,7 @@ struct bgfx_interface_vtbl
void (*set_view_order)(bgfx_view_id_t _id, uint16_t _num, const bgfx_view_id_t* _order);
void (*set_view_shading_rate)(bgfx_view_id_t _id, bgfx_shading_rate_t _shadingRate);
void (*reset_view)(bgfx_view_id_t _id);
bgfx_encoder_t* (*encoder_begin)(bool _forThread);
bgfx_encoder_t* (*encoder_begin)(bool _forceNewEncoder);
void (*encoder_end)(bgfx_encoder_t* _encoder);
void (*encoder_set_marker)(bgfx_encoder_t* _this, const char* _name, int32_t _len);
void (*encoder_set_state)(bgfx_encoder_t* _this, uint64_t _state, uint32_t _rgba);

46
scripts/bgfx.idl
View File

@@ -2271,13 +2271,51 @@ func.resetView { section = "Views" }
"void"
.id "ViewId" --- _id View id.
--- Begin submitting draw calls from thread.
--- Begin submitting draw calls from thread. Obtains an encoder that can be
--- used to submit draw calls, compute dispatches, and state changes.
---
--- In multithreaded mode (`BGFX_CONFIG_MULTITHREADED=1`), multiple threads
--- can each obtain their own encoder and submit draw calls in parallel.
--- Each encoder writes into its own uniform buffer, so there is no
--- contention between threads. The maximum number of simultaneous encoders
--- is configured via `Limits.maxEncoders` in `bgfx::Init` (default: 8).
---
--- When called from the API thread (the thread that called `bgfx::init`)
--- with `_forceNewEncoder` set to `false`, the default internal encoder
--- (encoder 0) is returned. This is the same encoder used by the legacy
--- non-encoder API (`bgfx::setState`, `bgfx::submit`, etc.). When called
--- from a worker thread (or with `_forceNewEncoder` set to `true`), a new
--- encoder is allocated from the encoder pool.
---
--- @remarks
--- The returned `Encoder` pointer is valid until `bgfx::end` is called
--- with it. All encoders must be ended before `bgfx::frame` is called.
--- If `bgfx::frame` is called while encoders are still active, it will
--- wait for them to finish. Returns `NULL` if no encoder slots are
--- available (all `maxEncoders` slots are in use).
--- See also: `bgfx::end`, `bgfx::frame`.
---
func.begin { cname = "encoder_begin", section = "Encoder" }
"Encoder*" --- Encoder.
.forThread "bool" --- Explicitly request an encoder for a worker thread.
"Encoder*" --- Encoder.
.forceNewEncoder "bool" --- Force allocation of a new encoder from the pool,
--- even when called from the API thread.
{ default = false }
--- End submitting draw calls from thread.
--- End submitting draw calls from thread. Returns the encoder obtained from
--- `bgfx::begin` back to the encoder pool.
---
--- After this call the `Encoder` pointer is no longer valid and must not
--- be used. The encoder's recorded draw calls and state changes are finalized
--- and will be included in the next frame when `bgfx::frame` is called.
---
--- @remarks
--- Must be called from the same thread that called `bgfx::begin` for
--- this encoder. All encoders must be ended before `bgfx::frame` is
--- called. The default encoder (encoder 0, used by the legacy API) is
--- managed internally and does not need to be passed to `bgfx::end`;
--- passing it is harmless but has no effect.
--- See also: `bgfx::begin`, `bgfx::frame`.
---
func["end"] { cname = "encoder_end", section = "Encoder" }
"void"
.encoder "Encoder*" --- Encoder.

4
src/bgfx.idl.inl
View File

@@ -716,9 +716,9 @@ BGFX_C_API void bgfx_reset_view(bgfx_view_id_t _id)
bgfx::resetView((bgfx::ViewId)_id);
}
BGFX_C_API bgfx_encoder_t* bgfx_encoder_begin(bool _forThread)
BGFX_C_API bgfx_encoder_t* bgfx_encoder_begin(bool _forceNewEncoder)
{
return (bgfx_encoder_t*)bgfx::begin(_forThread);
return (bgfx_encoder_t*)bgfx::begin(_forceNewEncoder);
}
BGFX_C_API void bgfx_encoder_end(bgfx_encoder_t* _encoder)