Release notes

What’s new #

Content Development #

Curly brackets position in Data Binding expressions

The curly brackets in data binding expressions will now automatically expand until the end of the property chain during evaluation. For example, the expression {{model.property1}}.property2 + {{anotherModel}}.property1.property2.property3 will be evaluated as if it was written as {{model.property1.property2}} + {{anotherModel.property1.property2.property3}}.

That change will have a performance gain for expressions that were unintentionally written with properties outside of the curly brackets, because such expressions were evaluated through a JS function even for C++ models and properties.

In the same time, new properties that were dynamically added to the model in JS will still be accessible. This case also has a performance gain because the expression will be evaluated in C++ without compiling to a JS function.

cppModel.cppProperty.scriptedProperty = 25;
engine.updateWholeModel(cppModel);
engine.synchronizeModels();
...
// The following lines are equivalent
<div data-bind-value="{{cppModel.cppProperty.scriptedProperty}}"></div>
<div data-bind-value="{{cppModel.cppProperty}}.scriptedProperty"></div>
<div data-bind-value="{{cppModel}}.cppProperty.scriptedProperty"></div>

Note that complex expressions which use JS functions and can’t be evaluated by Gameface will still be compiled to a JS function.

Global Backdrop Filter

Gameface now supports an alternative approach to having a backdrop filter effect in UIs - “Global Backdrop Filter”. This alternative to the traditional backdrop filter has better performance and can potentially save up GPU memory. However, it also has the limitation of forcing every DOM element utilizing it to have the same backdrop filter effect.

For more details, see the documentation for Global Backdrop Filter

Unreal Engine #

New delegates for modifying Library, System and View options

The Gameface integration for Unreal Engine now provides new ModifyLibraryParams, ModifySystemSettings, and ModifyViewSettings delegates for modifying all Gameface Library, System and View options.

ModifyLibraryParams, ModifySystemSettings, and ModifyViewSettings delegates are located inside ICohtmlPlugin.h, and are called right before creating a Gameface Library, System and View, passing a pointer to the already populated settings.

Migration guide #

Pixel Shader Changes

Changes in the shaders #

Color Matrix multiplication #

There is a color matrix that is now applied to the pixel color at the end of these shaders: CohColorMixingPS.hlsl, CohRenoirShaderPS.hlsl, CohShadeGeometry.ihlsl and CohShadeGeometryRare.ihlsl. To extract the offset, which points to the color matrix coefficients (5 float4s), from the pixel shader constant buffer data, you can use the following approach:

	int vs, ps, shaderType;
	decode(input.VaryingData, vs, ps, shaderType);
	float4 perCommandData = Data_PS[ps];
	int sharedCBOffset = int(perCommandData.x);
	int commonPSCBDataOffset = max(0, sharedCBOffset + SHARED_PS_DATA_OFFSET);
	int colorMatrixOffset = int(Data_PS[commonPSCBDataOffset].z);

If the colorMatrixOffset is not -1, then there is a color matrix at the given offset that needs to be applied to the output color. You can refer to the shader files mentioned above to see how the color matrix is applied in practice. As for an example implementation of the multiplication itself, check out the ApplyColorMatrix() function inside CohCommonPS.ihlsl. All custom shaders have to be modified to also apply the color matrix.

Image alpha premultiplication inside the shaders #

If you rely on custom shaders, you’ll need to update the pixel shader additional flags in CohCommonPS.ihlsl with the following new value:

static const int PSAF_ShouldPremultiplyAlpha = 0x40;

This flag specifies whether the shader should manually apply alpha premultiplication to the sampled texture color before applying the color matrix:

float4 outColor = SAMPLE2D(txBuffer, uvPoint);
if (IS_SET(additionalFlags, PSAF_ShouldPremultiplyAlpha))
{
	outColor.rgb *= outColor.a;
}

This change is necessary because some images do not come with premultiplied alpha (as indicated by the ImageProperties::IMP_Premultiplied flag). Previously, alpha premultiplication was handled by the blend mode. However, with the introduction of implicit color matrix calculations in the shader pipeline, the alpha must now be premultiplied manually before the color matrix is applied.

Changes to the gradient shaders #

In order to improve the batching of the gradients, we have made some changes to the following shader files - CohRenoirShaderVS.hlsl, CohRenoirShaderPS.hlsl and CohStandardCommon.ihlsl. The changes include moving some calculations from the vertex shader to the pixel shader, some restructuring of the constant buffers, and a data member removal. If you maintain custom shaders you must align them with the new structure. An overview of all impacted files and their changes:

1. CohRenoirShaderVS.hlsl:

   • Removed the maskScaleAndOffset calculation (now done in the pixel shader).

2. CohStandardCommon.ihlsl

   • Removed VaryingParam1 member from the PS_INPUT_RENOIR_SHADER structure, as it is no longer needed.

3. Constant Buffer Restructuring

   • maskScaleAndOffset moved from the Data_VS buffer to the Data_PS buffer.

4. CohRenoirShaderPS.hlsl

   • The shaderType and opacity are now extracted from the perCommandData in the Data_PS buffer.
   • Added gradient repeat scale and offset to the per batch data inside the Data_PS buffer. See below how they are applied.
   • Mask UVs are now calculated in the pixel shader using the new maskScaleAndOffset location in the per command data of the Data_PS buffer.

   Preview of the new changes and how to extract the information mentioned above:

// CohRenoirShaderPS.hlsl
...

int vs, ps, shaderType;
decode(input.VaryingData, vs, ps, shaderType);
float4 perCommandData = Data_PS[ps++];
// Example extraction of the shader type and opacity from their new location in the buffer
shaderType = int(perCommandData.y);
float opacity = perCommandData.w;

...

if (IS_SET(shaderType, PSTF_GradientRepeat))
{
	float repeatScale = Data_PS[sharedCBOffset].x;
	float repeatOffset = Data_PS[sharedCBOffset++].y;

	tVal = Frac(tVal * repeatScale + repeatOffset);
}
else if (IS_SET(shaderType, PSTF_GradientReflect))
{
	float repeatScale = Data_PS[sharedCBOffset].x;
	float repeatOffset = Data_PS[sharedCBOffset++].y;

	tVal = Mirror(tVal * repeatScale + repeatOffset);
}

...

// In the case of a mask we now calculate the UVs using the `maskScaleAndOffset` from the `Data_PS` buffer.
if (IS_SET(shaderType, PSTF_HasMask))
{
	float4 maskScaleAndOffset = Data_PS[ps];
	float2 maskUV = input.ScreenNormalPosition.xy * maskScaleAndOffset.xy + maskScaleAndOffset.zw;

	float mask = SAMPLE2D(txMask, maskUV).a;
	colorTemp *= mask;
}

Changelog #

Version 1.69.0 #