Towards a unified sg_begin_pass()

[floooh]

Baking the discussion in https://github.com/floooh/sokol/pull/899 into a ticket:

The only difference between a 'default pass' and a 'pass' is that a default pass renders into an externally provided set of surfaces (a swapchain surface that's actually displayed, optionally an MSAA surface that's resolved into the swapchain surface, and also optionally a depth-stencil surface - these surfaces need to 'match' each other, all must have the same width and height, and the display surface and msaa surface must have the same pixel format).

Using a single sg_begin_pass() that works both for regular offscreen rendering, and for a pass that renders into an externally provided swapchain surface has the advantage that this is more flexible for situations where people want to render into multiple views/windows.

Proposal:

• a single sg_begin_pass() method that takes a pointer to a parameter struct
• the parameter struct needs to contain:
  • an sg_pass_action struct
  • an sg_pass handle (for regular 'offscreen passes' optionally provided)
  • a nested struct which provides 'external swapchain info':
    • width, height, sample count and color-/depth-pixel-format (for 'default passes')
    • per-backend nested structs with external resources (similar to sg_context_desc, but no more callbacks!)
  • get rid of the nested sg_context_desc struct in sg_context (no longer rneeded)

There needs to be a convenience helper function in sokol_glue.h similar to sapp_sgcontext() which provides the external swapchain info struct filled in from sokol_app.h.

Further things to consider:

• get rid of the sg_context stuff alltogether?
  • need to come up with a solution for the GLFW multiwindow sample
• get rid of baked pass objects?
  • on some backends there's some non-trivial stuff happening when creating a pass, but OTH sg_begin_pass isn't exactly a high frequency call
  • would this complicate things for a potential Vulkan backend?
• should it be possible to optionally pass sokol-gfx images as swapchain depth-stencil- and msaa-surface? This might make it a bit easier to write a platform-specific swapchain implementation outside of sokol_app.h, but the user needs to make sure that the surfaces are compatibel (matching size and pixel formats)

[danielchasehooper]

FWIW, this might be an opportunity to consider renaming things a bit so the concept of render destination and concept of series of commands have distinct names (instead of both being called pass). Off the top of my head, a render destination could be called a sg_target or sg_destination while sg_begin_pass could continue to be used to wrap a series of commands.

[floooh]

Hmm, usually those things are called render pass in APIs which encapsulate render pass state as objects (e.g. https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCreateRenderPass.html), and VkRenderPassCreateInfo is roughly the equivalent to sg_pass_desc: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkRenderPassCreateInfo.html

An option which I keep rolling around in my head (and also mentioned in the OP of this issue) is to get rid of baked pass objects alltogether, in all other 3D APIs except Vulkan (and only up to 1.2 I think?), passes are 'transient' objects, sometimes not even directly exposed to the API user (only indirectly via 'render pass encoders'). But in some of the backends there's potentially expensive stuff happening in _sg_*create_pass which then may need to move into _sg_begin_pass (at least the framebuffer setup in GL, for D3D11 the RTV creation could move into _sg_d3d11_create_image.

I will need to tinker around with this a bit.

[floooh]

This is now implemented (https://github.com/floooh/sokol/pull/985)