Used in sg_begin_pass() to provide details about an external swapchain
(pixel formats, sample count and backend-API specific render surface objects).
The following information must be provided:
- the width and height of the swapchain surfaces in number of pixels,
- the pixel format of the render- and optional msaa-resolve-surface
- the pixel format of the optional depth- or depth-stencil-surface
- the MSAA sample count for the render and depth-stencil surface
If the pixel formats and MSAA sample counts are left zero-initialized,
their defaults are taken from the sg_environment struct provided in the
sg_setup() call.
The width and height *must* be > 0.
Additionally the following backend API specific objects must be passed in
as 'type erased' void pointers:
GL:
- on all GL backends, a GL framebuffer object must be provided. This
can be zero for the default framebuffer.
D3D11:
- an ID3D11RenderTargetView for the rendering surface, without
MSAA rendering this surface will also be displayed
- an optional ID3D11DepthStencilView for the depth- or depth/stencil
buffer surface
- when MSAA rendering is used, another ID3D11RenderTargetView
which serves as MSAA resolve target and will be displayed
WebGPU (same as D3D11, except different types)
- a WGPUTextureView for the rendering surface, without
MSAA rendering this surface will also be displayed
- an optional WGPUTextureView for the depth- or depth/stencil
buffer surface
- when MSAA rendering is used, another WGPUTextureView
which serves as MSAA resolve target and will be displayed
Metal (NOTE that the roles of provided surfaces is slightly different
than on D3D11 or WebGPU in case of MSAA vs non-MSAA rendering):
- A current CAMetalDrawable (NOT an MTLDrawable!) which will be presented.
This will either be rendered to directly (if no MSAA is used), or serve
as MSAA-resolve target.
- an optional MTLTexture for the depth- or depth-stencil buffer
- an optional multisampled MTLTexture which serves as intermediate
rendering surface which will then be resolved into the
CAMetalDrawable.
NOTE that for Metal you must use an ObjC __bridge cast to
properly tunnel the ObjC object id through a C void*, e.g.:
On all other backends you shouldn't need to mess with the reference count.
It's a good practice to write a helper function which returns an initialized
sg_swapchain structs, which can then be plugged directly into
sg_pass.swapchain. Look at the function sglue_swapchain() in the sokol_glue.h
as an example
sg_swapchain
Used in sg_begin_pass() to provide details about an external swapchain (pixel formats, sample count and backend-API specific render surface objects).
The following information must be provided:
- the width and height of the swapchain surfaces in number of pixels, - the pixel format of the render- and optional msaa-resolve-surface - the pixel format of the optional depth- or depth-stencil-surface - the MSAA sample count for the render and depth-stencil surface
If the pixel formats and MSAA sample counts are left zero-initialized, their defaults are taken from the sg_environment struct provided in the sg_setup() call.
The width and height *must* be > 0.
Additionally the following backend API specific objects must be passed in as 'type erased' void pointers:
GL: - on all GL backends, a GL framebuffer object must be provided. This can be zero for the default framebuffer.
D3D11: - an ID3D11RenderTargetView for the rendering surface, without MSAA rendering this surface will also be displayed - an optional ID3D11DepthStencilView for the depth- or depth/stencil buffer surface - when MSAA rendering is used, another ID3D11RenderTargetView which serves as MSAA resolve target and will be displayed
WebGPU (same as D3D11, except different types) - a WGPUTextureView for the rendering surface, without MSAA rendering this surface will also be displayed - an optional WGPUTextureView for the depth- or depth/stencil buffer surface - when MSAA rendering is used, another WGPUTextureView which serves as MSAA resolve target and will be displayed
Metal (NOTE that the roles of provided surfaces is slightly different than on D3D11 or WebGPU in case of MSAA vs non-MSAA rendering):
- A current CAMetalDrawable (NOT an MTLDrawable!) which will be presented. This will either be rendered to directly (if no MSAA is used), or serve as MSAA-resolve target. - an optional MTLTexture for the depth- or depth-stencil buffer - an optional multisampled MTLTexture which serves as intermediate rendering surface which will then be resolved into the CAMetalDrawable.
NOTE that for Metal you must use an ObjC __bridge cast to properly tunnel the ObjC object id through a C void*, e.g.:
swapchain.metal.current_drawable = (__bridge const void*) [mtkView currentDrawable];
On all other backends you shouldn't need to mess with the reference count.
It's a good practice to write a helper function which returns an initialized sg_swapchain structs, which can then be plugged directly into sg_pass.swapchain. Look at the function sglue_swapchain() in the sokol_glue.h as an example