Skip to content

proposal: swapchain & presentation rework #197

@rajveermalviya

Description

@rajveermalviya

Context

Currently the WGPUSwapChain API diverts from the js spec; this proposal tries to match the js spec while also maintaining the functionality that is required in the native context.

Keep in mind this proposal is mostly what wgpu-rs already exposes so it tries to match it.

Update present mode enum to add automatic modes

// matches wgpu
// https://docs.rs/wgpu-types/latest/wgpu_types/enum.PresentMode.html
typedef enum WGPUPresentMode {
	WGPUPresentMode_Fifo = 0x00000000, // default
	// VK_PRESENT_MODE_FIFO_RELAXED_KHR
	WGPUPresentMode_FifoRelaxed = 0x00000001, // new
	WGPUPresentMode_Immediate = 0x00000002,
	WGPUPresentMode_Mailbox = 0x00000003,
	WGPUPresentMode_Force32 = 0x7FFFFFFF
} WGPUPresentMode;

Remove WGPUSwapChain (and merge it's interface into Surface api)

In the js spec this was done a while ago.
Fixes: #88

// matches wgpu
// https://docs.rs/wgpu-types/latest/wgpu_types/enum.CompositeAlphaMode.html
typedef enum WGPUCompositeAlphaMode {
	// Chooses between Opaque & Inherit whichever is available.
	WGPUCompositeAlphaMode_Auto = 0x00000000,
	WGPUCompositeAlphaMode_Opaque = 0x00000001,
	WGPUCompositeAlphaMode_PreMultiplied = 0x00000002,
	WGPUCompositeAlphaMode_UnPreMultiplied = 0x00000003,
	WGPUCompositeAlphaMode_Inherit = 0x00000004,
	WGPUCompositeAlphaMode_Force32 = 0x7FFFFFFF
} WGPUCompositeAlphaMode;

// Replaces WGPUSwapChainDescriptor
typedef struct WGPUSurfaceConfiguration {
	WGPUChainedStruct const * nextInChain;
	WGPUDevice device;
	WGPUTextureFormat format;
	WGPUTextureUsage usage;
	size_t viewFormatCount;
	WGPUTextureFormat const * viewFormats;
	WGPUCompositeAlphaMode alphaMode;

	uint32_t width;
	uint32_t height;
	WGPUPresentMode presentMode;
} WGPUSurfaceConfiguration;

// Replaces wgpuDeviceCreateSwapChain
void wgpuSurfaceConfigure(WGPUSurface surface, WGPUSurfaceConfiguration const * config);
// This function probably should be skipped but we need to match js spec.
void wgpuSurfaceUnconfigure(WGPUSurface surface);

Provide current Texture instead of TextureView

Fixes: #89

typedef enum WGPUSurfaceGetCurrentTextureError {
	WGPUSurfaceGetCurrentTextureError_NoError = 0x00000000,
	WGPUSurfaceGetCurrentTextureError_Timeout = 0x00000001,
	WGPUSurfaceGetCurrentTextureError_Outdated = 0x00000002,
	WGPUSurfaceGetCurrentTextureError_Lost = 0x00000003,
	WGPUSurfaceGetCurrentTextureError_OutOfMemory = 0x00000004,
	WGPUSurfaceGetCurrentTextureError_DeviceLost = 0x00000005,
	WGPUSurfaceGetCurrentTextureError_Force32 = 0x7FFFFFFF
} WGPUSurfaceGetCurrentTextureError;

typedef struct WGPUSurfaceTexture {
	WGPUTexture texture;
	// If suboptimal is true presentation will still succeed,
	// but the internal swapchain is no longer configured optimally
	// for the surface it targets. Applications should recreate
	// their swapchain at the next convenient opportunity.
	bool suboptimal;
	WGPUSurfaceGetCurrentTextureError error;
} WGPUSurfaceTexture;

// Replaces wgpuSwapChainGetCurrentTextureView
void wgpuSurfaceGetCurrentTexture(WGPUSurface surface, WGPUSurfaceTexture * surfaceTexture);

Provide a way to query information about the surface

typedef struct WGPUSurfaceCapabilities {
	WGPUChainedStructOut * nextInChain;
	size_t formatCount;
	WGPUTextureFormat * formats;
	size_t presentModeCount;
	WGPUPresentMode * presentModes;
	size_t alphaModeCount;
	WGPUCompositeAlphaMode * alphaModes;
} WGPUSurfaceCapabilities;

void wgpuSurfaceGetCapabilities(WGPUSurface surface, WGPUAdapter adapter, WGPUSurfaceCapabilities * capabilities);
void wgpuSurfaceCapabilitiesFreeMembers(WGPUSurfaceCapabilities capabilities);

Note: wgpuSurfaceGetCapabilities could replace current wgpuSurfaceGetPreferredFormat by guaranteeing that first format is the preferred one. But removing wgpuSurfaceGetPreferredFormat will divert from js spec.

Move Present function to Surface

// DevicePushErrorScope/DevicePopErrorScope can be used to catch errors
void wgpuSurfacePresent(WGPUSurface surface);

open discussion: presentation extensions

frame pacing & damage support
ref: gfx-rs/wgpu#2869

Metadata

Metadata

Assignees

No one assigned

    Labels

    has resolutionIssue is resolved, just needs to be donepresentationPresenting images to surfaces like windows and canvases

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions