Global Backdrop Filter

Overview #

The “Global Backdrop Filter” feature of Gameface is an alternative approach to doing a backdrop filter effect on an HTML page. In certain scenarios, it can provide better CPU performance as well as save GPU memory used by Gameface. The feature is best suited where there are lots of elements on screen that have the same backdrop filter effect. The limitations are:

• Every DOM element utilizing the global backdrop filter must apply the effect on the background behind it
• DOM elements utilizing the global backdrop filter cannot filter other DOM elements behind them
• The client code is responsible for doing the content filtering

Regular backdrop filter implementation overview #

Gameface has support for the backdrop-filter CSS property. Content behind the UI texture can be filtered by the backdrop filter thanks to the client-provided “user background texture”. This backdrop filter scheme is flexible as it allows individual elements in the DOM to apply their backdrop filters that filter content in different ways. However, some performance implications should be considered:

• Gameface always redraws elements with backdrop-filter every frame as the content in the user background texture is assumed to be changed every frame. This can lead to big and heavy repaints of parts of the UI.
• Gameface applies the filters from the backdrop-filter individually to every element. Even though it is a common use case that all elements with a backdrop have the same or similar filters, the rendering logic will still handle every element individually and filter parts of the background in pieces. This is inefficient and makes poor use of GPU resources.

Global Backdrop Filter #

To address those issues, Gameface has the “Global Backdrop Filter” feature. The feature gives frontend developers the ability to mark certain elements in the DOM as having a backdrop filter. The integration code then gets information about which parts of the user background should be filtered. This means that all of the to-be-filtered content can be handled at once with the same filter. Such a scheme also gives the integration code more control over how the filtering is done.

A common use case for this is to have some UI elements that blur the 3D scene content behind them. The Global Backdrop Filter allows client code to have efficient filtering and flexible filtering of the relevant parts of the texture with the 3D scene.

The Global Backdrop Filter addresses both pitfalls of the normal backdrop filter.

• Elements that utilize the Global Backdrop Filter are not redrawn every frame. This can potentially bring a big performance improvement in the UI
• The whole background filtering is applied in one go. This again saves performance on the CPU and GPU. Also, Gameface uses fewer temporary textures for the rendering which can save some GPU memory.

Frontend usage #

On the frontend, Gameface introduces the new coh-enable-backdrop-filter CSS property. It accepts floating point values in the range [0.0, 1.0] where:

• 0.0 (default) – no global backdrop filter is applied to the element.
• 1.0 – the DOM element is considered to have the full effect of the global backdrop filter applied to it
• anything in between – the backdrop filter is partially applied. The resulting content is only filtered to some extent. This allows for smooth transitions of backdrop filter effects. The coh-enable-backdrop-filter property supports both animation and transitions, enabling dynamic effects like gradual blur fades or filter intensity changes.

Elements with a global backdrop filter applied are meant to filter the user content “behind them”. That is, when the UI texture is drawn on top of the rendered 3D scene, the scene texture is considered “user background” and it is behind the UI content.

Here is an Example usage in the HTML/CSS of a page:

<style>
	<!-- elements with this class will filter the user background content behind them -->
	.globalBackdropFilter {
		coh-enable-backdrop-filter: 1.0;
	}

	.element {
		width: 100px;
		height: 100px;
		<!-- elements utilizing the backdrop filter should have some partially transparent parts -->
		background: rgba(64, 64, 128, 0.5);
	}
</style>

<body>
	<!-- element with global backdrop filter applied -->
	<div class="element globalBackdropFilter"></div>

	<!-- no backdrop filter applied -->
	<div class="element"></div>

	<!-- element with global backdrop filter applied -->
	<div class="element globalBackdropFilter"></div>
</body>

Integration usage #

In the C++ integration, the global backdrop filter is handled with a “Global Backdrop Filter Mask”. This is a user-provided texture that Gameface will draw onto. The non-zero pixel values tell the client code where the filtering of the user background texture should happen. Gameface also assumes that the provided global backdrop filter mask texture will be a single-channel 8-bit per pixel texture.

The overall idea is as follows:

• Client code sets the global backdrop filter mask with cohtml::View::SetGlobalBackdropFilterMask. The texture is provided as an opaque texture pointer. During the next cohtml::ViewRenderer::Paint, Gameface will wrap this client-provided texture in the renderer backend with the BRC_WrapUserRT resource command.
• During calls to cohtml::ViewRenderer::Paint, Gameface will draw to the provided global backdrop filter mask. The drawn content will be the bounding boxes of the elements marked with coh-enable-backdrop-filter different than 0.0. This means that after the cohtml::ViewRenderer::Paint call, the global backdrop filter mask shows the places where the 3D scene texture should be filtered.
• The client code then filters the background texture while respecting the global backdrop filter mask.
• The client code draws the UI texture on top of the user background texture.

The effect of this is that the elements marked with coh-enable-backdrop-filter different from 0.0 are drawn on top of the filtered content. The appearance is as if the UI elements themselves are filtering the content that is behind them.

As previously mentioned, it is up to the integration code to filter the background texture in some way. No information about the type of filtering is supplied in HTML/CSS and hence Gameface gives no information to the integration code on how the content should be filtered.

Here is an example UI texture and the corresponding global backdrop filter mask rendered by Gameface. All of the rectangle elements are marked with coh-enable-backdrop-filter different than 0.0. They are rendered as regular elements in the UI texture.

The resulting global backdrop filter mask shows the places that should filter the background behind them.

The following diagram shows the global backdrop filter scheme.

In this case, the scene texture is blurred only in the places where the global backdrop filter has values.

In C++ code, all the logic can look something like this:

//This assumes that the DirectX 11 backend is in use
OpaqueUserTextureDx11 userObject;
userObject.Resource = globalBackdropFilterTexturePtr;
userObject.SRV = globalBackdropFilterTextureSRVPtr;
userObject.RTV = globalBackdropFilterTextureRTVPtr;

renoir::Texture2D desc;
description.Width = viewWidth;
description.Height = viewHeight;
description.Format = rneoir::PF_R8;
description.ContentRectX = 0;
description.ContentRectY = 0;
description.ContentRectWidth = viewWidth;
description.ContentRectHeight = viewHeight;

// Set the global backdrop filter mask. Gameface will render the bounding boxes of
// the elements utilizing the global backdrop filter on the provided texture.
view->SetGlobalBackdropFilterMask(&userObject, desc);

// During the next cohtml::ViewRenderer::Paint call, Gameface will send a BRC_WrapUserRT command
// to the renderer backend what to register the provided texture
viewRenderer->Paint(frameId, true);

// After the cohtml::ViewRenderer::Paint call, Gameface will have rendered the content the
// global backdrop filter mask

// The client code now should filter the background content based on the mask
clientRenderer->FilterTextureWithMaks(sceneTexture, globalBackdropFilterTexturePtr);

// The client code then should draw the UI texture on top of the scene texture
clientRenderer->DrawOntoTexture(sceneTexture, uiTexture);

Example Usage in the Player Application #

The Player Application that comes with Gameface supports an example usage of the global backdrop filter. The Player can be launched with the following command line arguments.

• --user-background <path-to-some-image> – loads the image as a texture and uses it like a user background texture. The UI texture will be composed on top of it and backdrop filter effects can be tested.
• --global-backdrop-filter-type blur – enables the blur global backdrop filter. DOM elements marked with coh-enable-backdrop-filter different from 0.0 will blur the loaded user background content behind them

A page that utilizes the coh-enable-backdrop-filter property can then be loaded and properly displayed.