mirror of
https://github.com/bkaradzic/bgfx.git
synced 2026-06-08 03:13:52 +00:00
IDL: Improve docs. (#3614)
This commit is contained in:
Branimir Karadžić
committed by
GitHub
GitHub
parent
c10271dc28
commit
3e6455e6b0
@@ -15,6 +15,8 @@ API Reference
|
||||
General
|
||||
-------
|
||||
|
||||
General API for initialization, shutdown, frame management, debug, and querying renderer information.
|
||||
|
||||
Initialization and Shutdown
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -42,6 +44,8 @@ Updating
|
||||
Reset
|
||||
*****
|
||||
|
||||
Reset flags control back-buffer resolution, MSAA, vsync, and other global rendering settings.
|
||||
|
||||
.. doxygendefine:: BGFX_RESET_NONE
|
||||
.. doxygendefine:: BGFX_RESET_FULLSCREEN
|
||||
.. doxygendefine:: BGFX_RESET_VSYNC
|
||||
@@ -61,6 +65,8 @@ Reset
|
||||
Frame
|
||||
*****
|
||||
|
||||
Frame flags and the ``bgfx::frame`` call to advance to the next frame.
|
||||
|
||||
.. doxygendefine:: BGFX_FRAME_NONE
|
||||
.. doxygendefine:: BGFX_FRAME_DEBUG_CAPTURE
|
||||
.. doxygendefine:: BGFX_FRAME_DISCARD
|
||||
@@ -73,11 +79,15 @@ Debug
|
||||
Debug Features
|
||||
**************
|
||||
|
||||
Enable or disable debug features.
|
||||
|
||||
.. doxygenfunction:: bgfx::setDebug
|
||||
|
||||
Debug Flags
|
||||
***********
|
||||
|
||||
Flags for ``bgfx::setDebug``.
|
||||
|
||||
.. doxygendefine:: BGFX_DEBUG_NONE
|
||||
.. doxygendefine:: BGFX_DEBUG_WIREFRAME
|
||||
.. doxygendefine:: BGFX_DEBUG_IFH
|
||||
@@ -88,6 +98,8 @@ Debug Flags
|
||||
Debug Text Display
|
||||
******************
|
||||
|
||||
Functions for printing debug text on screen.
|
||||
|
||||
.. doxygenfunction:: bgfx::dbgTextClear
|
||||
.. doxygenfunction:: bgfx::dbgTextPrintf
|
||||
.. doxygenfunction:: bgfx::dbgTextPrintfVargs
|
||||
@@ -99,6 +111,8 @@ Querying information
|
||||
Renderer
|
||||
********
|
||||
|
||||
Query the active rendering backend.
|
||||
|
||||
.. doxygenstruct:: bgfx::RendererType
|
||||
:members:
|
||||
|
||||
@@ -108,9 +122,13 @@ Renderer
|
||||
Capabilities
|
||||
************
|
||||
|
||||
Query GPU capabilities and limits.
|
||||
|
||||
Available Caps
|
||||
""""""""""""""
|
||||
|
||||
Individual capability flags.
|
||||
|
||||
.. doxygendefine:: BGFX_CAPS_ALPHA_TO_COVERAGE
|
||||
.. doxygendefine:: BGFX_CAPS_BLEND_INDEPENDENT
|
||||
.. doxygendefine:: BGFX_CAPS_COMPUTE
|
||||
@@ -150,6 +168,8 @@ Available Caps
|
||||
Statistics
|
||||
**********
|
||||
|
||||
Per-frame rendering statistics.
|
||||
|
||||
.. doxygenstruct:: bgfx::ViewStats
|
||||
:members:
|
||||
|
||||
@@ -265,6 +285,8 @@ All state is cleared after calling ``bgfx::submit``.
|
||||
Debug
|
||||
*****
|
||||
|
||||
Debug markers for grouping draw calls in graphics debugging tools.
|
||||
|
||||
.. doxygenfunction:: bgfx::setName(ShaderHandle _handle, const char* _name, int32_t _len = INT32_MAX)
|
||||
.. doxygenfunction:: bgfx::setName(TextureHandle _handle, const char* _name, int32_t _len = INT32_MAX)
|
||||
.. doxygenfunction:: bgfx::setMarker
|
||||
@@ -272,11 +294,15 @@ Debug
|
||||
State
|
||||
*****
|
||||
|
||||
Configure render state for draw calls.
|
||||
|
||||
.. doxygenfunction:: bgfx::setState
|
||||
|
||||
State Flags
|
||||
***********
|
||||
|
||||
Render state flags for depth test, blending, culling, etc.
|
||||
|
||||
**Write**
|
||||
|
||||
.. doxygendefine:: BGFX_STATE_WRITE_R
|
||||
@@ -348,11 +374,15 @@ State Flags
|
||||
Stencil
|
||||
*******
|
||||
|
||||
Configure stencil test for draw calls.
|
||||
|
||||
.. doxygenfunction:: bgfx::setStencil
|
||||
|
||||
Stencil Flags
|
||||
*************
|
||||
|
||||
Stencil test configuration flags.
|
||||
|
||||
.. doxygendefine:: BGFX_STENCIL_TEST_LESS
|
||||
.. doxygendefine:: BGFX_STENCIL_TEST_LEQUAL
|
||||
.. doxygendefine:: BGFX_STENCIL_TEST_EQUAL
|
||||
@@ -375,6 +405,8 @@ Otherwise, use ``bgfx::setViewScissor``.
|
||||
Transform
|
||||
*********
|
||||
|
||||
Set model transform matrices for draw calls.
|
||||
|
||||
.. doxygenfunction:: bgfx::setTransform(const void* _mtx, uint16_t _num = 1)
|
||||
.. doxygenfunction:: bgfx::setTransform(uint32_t _cache, uint16_t _num = 1)
|
||||
.. doxygenfunction:: bgfx::allocTransform
|
||||
@@ -382,11 +414,15 @@ Transform
|
||||
Conditional Rendering
|
||||
*********************
|
||||
|
||||
Conditionally render based on occlusion query results.
|
||||
|
||||
.. doxygenfunction:: bgfx::setCondition
|
||||
|
||||
Buffers
|
||||
*******
|
||||
|
||||
Set vertex, index, and instance data buffers for draw calls.
|
||||
|
||||
.. doxygenstruct:: bgfx::TransientIndexBuffer
|
||||
:members:
|
||||
|
||||
@@ -415,11 +451,15 @@ Buffers
|
||||
Textures
|
||||
********
|
||||
|
||||
Bind textures to texture stages for draw calls.
|
||||
|
||||
.. doxygenfunction:: bgfx::setTexture
|
||||
|
||||
Uniforms
|
||||
********
|
||||
|
||||
Set shader uniform parameters for draw calls.
|
||||
|
||||
.. doxygenfunction:: bgfx::setViewUniform
|
||||
.. doxygenfunction:: bgfx::setFrameUniform
|
||||
.. doxygenfunction:: bgfx::setUniform
|
||||
@@ -442,6 +482,8 @@ Compute state is not preserved between compute dispatches; all state is cleared
|
||||
Buffers
|
||||
*******
|
||||
|
||||
Bind buffers to compute stages.
|
||||
|
||||
.. doxygenstruct:: bgfx::Access
|
||||
:members:
|
||||
|
||||
@@ -454,6 +496,8 @@ Buffers
|
||||
Images
|
||||
******
|
||||
|
||||
Bind texture images to compute stages.
|
||||
|
||||
.. doxygenfunction:: bgfx::setImage
|
||||
|
||||
Dispatch
|
||||
@@ -480,7 +524,7 @@ Shaders and Programs
|
||||
|
||||
.. note::
|
||||
|
||||
Shaders must be compiled with offline command line too shaderc.
|
||||
Shaders must be compiled with offline command line tool shaderc.
|
||||
|
||||
.. doxygenfunction:: bgfx::createShader
|
||||
.. doxygenfunction:: bgfx::getShaderUniforms
|
||||
|
||||
@@ -1150,7 +1150,7 @@ func.vertexConvert { section = "Miscellaneous" }
|
||||
.num "uint32_t" --- Number of vertices to convert from source to destination.
|
||||
{ default = 1 }
|
||||
|
||||
--- Weld vertices.
|
||||
--- Weld vertices. Returns number of unique vertices after welding.
|
||||
func.weldVertices { section = "Miscellaneous" }
|
||||
"uint32_t" --- Number of unique vertices after vertex welding.
|
||||
.output "void*" --- Welded vertices remapping table. The size of buffer
|
||||
@@ -1402,7 +1402,7 @@ func.destroy { cname = "destroy_index_buffer", section = "Index Buffers" }
|
||||
"void"
|
||||
.handle "IndexBufferHandle" --- Static index buffer handle.
|
||||
|
||||
--- Create vertex layout.
|
||||
--- Create vertex layout. Vertex layouts are used to describe the format of vertex data.
|
||||
func.createVertexLayout { section = "Vertex Buffers" }
|
||||
"VertexLayoutHandle"
|
||||
.layout "const VertexLayout &" --- Vertex layout.
|
||||
@@ -2063,7 +2063,8 @@ func.destroy { cname = "destroy_uniform", section = "Uniforms" }
|
||||
"void"
|
||||
.handle "UniformHandle" --- Handle to uniform object.
|
||||
|
||||
--- Create occlusion query.
|
||||
--- Create occlusion query. Occlusion queries allow the GPU to determine
|
||||
--- if any pixels passed the depth test.
|
||||
func.createOcclusionQuery { section = "Occlusion Query" }
|
||||
"OcclusionQueryHandle" --- Handle to occlusion query object.
|
||||
|
||||
@@ -2467,6 +2468,7 @@ func.Encoder.setVertexBuffer { conly, cname = "set_dynamic_vertex_buffer" }
|
||||
.startVertex "uint32_t" --- First vertex to render.
|
||||
.numVertices "uint32_t" --- Number of vertices to render.
|
||||
|
||||
--- Set vertex buffer for draw primitive.
|
||||
func.Encoder.setVertexBuffer { cname = "set_dynamic_vertex_buffer_with_layout", section = "Draw/Buffers" }
|
||||
"void"
|
||||
.stream "uint8_t" --- Vertex stream.
|
||||
@@ -3346,6 +3348,7 @@ func.blit { section = "Blit" }
|
||||
-- Documentation sections for RST generation
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
--- General API for initialization, shutdown, frame management, debug, and querying renderer information.
|
||||
section("General", 1)
|
||||
|
||||
--- Initialization and Shutdown
|
||||
@@ -3354,28 +3357,37 @@ section("Initialization and Shutdown", 2)
|
||||
--- Updating
|
||||
section("Updating", 2)
|
||||
|
||||
--- Reset flags control back-buffer resolution, MSAA, vsync, and other global rendering settings.
|
||||
section("Reset", 3)
|
||||
|
||||
--- Frame flags and the ``bgfx::frame`` call to advance to the next frame.
|
||||
section("Frame", 3)
|
||||
|
||||
--- Debug
|
||||
section("Debug", 2)
|
||||
|
||||
--- Enable or disable debug features.
|
||||
section("Debug Features", 3)
|
||||
|
||||
--- Flags for ``bgfx::setDebug``.
|
||||
section("Debug Flags", 3)
|
||||
|
||||
--- Functions for printing debug text on screen.
|
||||
section("Debug Text Display", 3)
|
||||
|
||||
--- Querying information
|
||||
section("Querying information", 2)
|
||||
|
||||
--- Query the active rendering backend.
|
||||
section("Renderer", 3)
|
||||
|
||||
--- Query GPU capabilities and limits.
|
||||
section("Capabilities", 3)
|
||||
|
||||
--- Individual capability flags.
|
||||
section("Available Caps", 4)
|
||||
|
||||
--- Per-frame rendering statistics.
|
||||
section("Statistics", 3)
|
||||
|
||||
--- Platform specific
|
||||
@@ -3417,14 +3429,19 @@ section("Encoder", 2)
|
||||
--- All state is cleared after calling ``bgfx::submit``.
|
||||
section("Draw", 2)
|
||||
|
||||
--- Debug markers for grouping draw calls in graphics debugging tools.
|
||||
section("Debug", 3)
|
||||
|
||||
--- Configure render state for draw calls.
|
||||
section("State", 3)
|
||||
|
||||
--- Render state flags for depth test, blending, culling, etc.
|
||||
section("State Flags", 3)
|
||||
|
||||
--- Configure stencil test for draw calls.
|
||||
section("Stencil", 3)
|
||||
|
||||
--- Stencil test configuration flags.
|
||||
section("Stencil Flags", 3)
|
||||
|
||||
--- Scissor
|
||||
@@ -3434,14 +3451,19 @@ section("Stencil Flags", 3)
|
||||
--- Otherwise, use ``bgfx::setViewScissor``.
|
||||
section("Scissor", 3)
|
||||
|
||||
--- Set model transform matrices for draw calls.
|
||||
section("Transform", 3)
|
||||
|
||||
--- Conditionally render based on occlusion query results.
|
||||
section("Conditional Rendering", 3)
|
||||
|
||||
--- Set vertex, index, and instance data buffers for draw calls.
|
||||
section("Buffers", 3)
|
||||
|
||||
--- Bind textures to texture stages for draw calls.
|
||||
section("Textures", 3)
|
||||
|
||||
--- Set shader uniform parameters for draw calls.
|
||||
section("Uniforms", 3)
|
||||
|
||||
--- Submit
|
||||
@@ -3454,8 +3476,10 @@ section("Submit", 3)
|
||||
--- Compute state is not preserved between compute dispatches; all state is cleared after calling ``bgfx::dispatch``.
|
||||
section("Compute", 2)
|
||||
|
||||
--- Bind buffers to compute stages.
|
||||
section("Buffers", 3)
|
||||
|
||||
--- Bind texture images to compute stages.
|
||||
section("Images", 3)
|
||||
|
||||
--- Dispatch
|
||||
@@ -3473,7 +3497,7 @@ section("Resources", 1)
|
||||
|
||||
--- Shaders and Programs
|
||||
---
|
||||
--- @remarks Shaders must be compiled with offline command line too shaderc.
|
||||
--- @remarks Shaders must be compiled with offline command line tool shaderc.
|
||||
section("Shaders and Programs", 2)
|
||||
|
||||
--- Uniforms
|
||||
|
||||
@@ -708,7 +708,19 @@ function codegen.doxygen_type(doxygen, func, cname)
|
||||
end
|
||||
end
|
||||
result[#result+1] = "///"
|
||||
return table.concat(result, "\n")
|
||||
|
||||
-- Collapse consecutive empty comment lines (///) into at most one.
|
||||
local collapsed = {}
|
||||
for _, line in ipairs(result) do
|
||||
local is_empty = (line == "///" or line == "/// ")
|
||||
local prev_empty = #collapsed > 0 and (collapsed[#collapsed] == "///" or collapsed[#collapsed] == "/// ")
|
||||
if is_empty and prev_empty then
|
||||
-- skip duplicate empty comment line
|
||||
else
|
||||
collapsed[#collapsed+1] = line
|
||||
end
|
||||
end
|
||||
return table.concat(collapsed, "\n")
|
||||
end
|
||||
|
||||
function codegen.doxygen_ctype(doxygen, func)
|
||||
@@ -728,7 +740,19 @@ function codegen.doxygen_ctype(doxygen, func)
|
||||
end
|
||||
result[#result+1] = " *"
|
||||
result[#result+1] = " */"
|
||||
return table.concat(result, "\n")
|
||||
|
||||
-- Collapse consecutive empty comment lines ( *) into at most one.
|
||||
local collapsed = {}
|
||||
for _, line in ipairs(result) do
|
||||
local is_empty = (line == " *" or line == " * ")
|
||||
local prev_empty = #collapsed > 0 and (collapsed[#collapsed] == " *" or collapsed[#collapsed] == " * ")
|
||||
if is_empty and prev_empty then
|
||||
-- skip duplicate empty comment line
|
||||
else
|
||||
collapsed[#collapsed+1] = line
|
||||
end
|
||||
end
|
||||
return table.concat(collapsed, "\n")
|
||||
end
|
||||
|
||||
local enum_temp = [[
|
||||
|
||||
@@ -10,6 +10,8 @@ function doxygen.load(filename)
|
||||
else
|
||||
line = string.format("%s [[%s]]", code, comment)
|
||||
end
|
||||
elseif line:match "^%-%-%-$" then
|
||||
line = "comment [[]]"
|
||||
end
|
||||
lines[#lines+1] = line
|
||||
end
|
||||
|
||||
Reference in New Issue
Block a user