html formatted docs

[nurpax]

Has HTML formatted docs ever been considered for the sokol APIs? Or maybe they're up somewhere and I just haven't found them?

The sokol_gfx.h is a pretty long source file and viewing it in the GitHub UI is a major PITA. Especially as GitHub seems to be making the source browser worse over time. :(

[nurpax]

The thought occured as I was trying to read about how to use render passes.

For example, is it ok to use the same pass multiple times in a single from? Like

sg_begin_pass(<rt A>)
sg_end_pass()

sg_begin_pass(<some other RT>)
sg_end_pass()

sg_begin_pass(<rt A>)
sg_end_pass()

I guess this is fine. But it's unclear if there are some serious downsides to this? Then I also searched for SG_LOADACTION_LOAD (which I guess I should use in the above example when using "rt A" again and noticed that it's only ever used in the Metal backend. I guess that's because in OpenGL multiple passes just means flipping between different render targets and if the load action is not a clear, it's more or less a no-op.

[floooh]

As for the render pass thingie: it's generally better to only do one pass per render target (e.g. think of passes as nodes in a dependency tree of render targets - not as the 'traditional' use of render passes for grouping similar render states into one pass - like opaque vs alpha rendering).

The Load/StoreAction thing is needed on Metal and WebGPU, and is needed for tiler-GPUs (since keeping the render target content around means that the tile content needs to be flushed back to memory and then loaded again from memory into GPU tiles in the later pass) - non-tiled GPUs don't need that extra load/store step because render targets are backed as a whole in GPU memory anyway.

TL;DR: Multiple passes into the same render target should be ok, but is less efficient on some GPUs. I also haven't encountered a situation yet where rendering into the same render target would need to be split into multiple passes.

Also: multiple passes are not allowed into swapchain targets (because the sg_end_pass() schedules a presentation).

As for the HTML docs stuff: I'm not a fan of Doxygen style auto-docs since they tend to have very little information density (might just as well jump to the struct definition right in the IDE), I do keep pondering though how to structure the per-struct and function documentation better for IDEs which extract the documentation for tooltips, because currently the tooltips are just too big.

[nurpax]

As for the HTML docs stuff: I'm not a fan of Doxygen style auto-docs since they tend to have very little information density (might just as well jump to the struct definition right in the IDE)

Yup, I also find auto-gen'd API refs pretty poor. The format tends to make developers tunnel vision into writing minimal per function doc strings and lose sight of higher level concepts. I guess what I was more after was some way of extracting the relevant sections into a separate HTML doc site.

might just as well jump to the struct definition right in the IDE

Heh yeah.. I'd agree except that I'm using Sokol in Zig and so ctrl-click symbol takes me here but no further:

pub extern fn sg_begin_pass([*c]const Pass) void;
pub fn beginPass(pass: Pass) void {
    sg_begin_pass(&pass);
}

[nurpax]

TL;DR: Multiple passes into the same render target should be ok, but is less efficient on some GPUs. I also haven't encountered a situation yet where rendering into the same render target would need to be split into multiple passes.

Also: multiple passes are not allowed into swapchain targets (because the sg_end_pass() schedules a presentation).

Oh ok, so it sounds like I should aim for one begin_pass/end_pass per frame in my code. This is for a 2d game engine like thing where I'm mostly running in Lua and I'd like it to be easy to render into arbitrary render targets without having to think much about passes or switching between render targets. In my case I'll most likely target almost everything into offscreen targets and then open the default pass only once at the end of the frame to compose everything and flip.

Thanks for the clarification!

[floooh]

Heh yeah.. I'd agree except that I'm using Sokol in Zig and so ctrl-click symbol takes me here but no further:

...ah hmm, good point... I currently can't find a ticket for it, but one thing I have somewhere buried on my mental todo list is to extract doc comments in the bindings generator scripts. At first I thought it's not possible to get comments in Clang's AST-dump, but apparently the Defold guys managed to do this for their bindings generator.

It's not very high on my priority list though tbh.

...but improving documentation for language bindings is definitely a good point (no matter how).