Shader cache

With shader caching, your application can skip costly shader recompilation in future stream sessions. If your application suffers from stuttering or slow load times, capturing a shader cache can significantly improve the experience for your end users.

With Amazon GameLift Streams, you can capture a shader cache from a specially designated stream session. Subsequent stream sessions of the application in all compatible stream groups automatically use the captured shader cache. Using the shader caching feature requires no code or other changes to your application.

Prerequisites

To use shader caching, you must meet the following requirements:

How shader caching works

Graphics applications such as games benefit from shader caches. Caches avoid repeated graphics-related processing and compilation work. To capture a shader cache from designated stream sessions, Amazon GameLift Streams collects system shader cache files automatically generated for your application. The service stores this cache and automatically applies it to future sessions on compatible stream groups. This reduces the time spent on processing shaders during future sessions. Generating or consuming a shader cache requires no changes to your application.

The shader caching lifecycle has three stages:

Capturing a shader cache

To capture a shader cache, follow these steps:

After generating a shader cache, you can improve it by starting further sessions with GAMELIFT_STREAMS_PACKAGED_SHADER_CACHE_CAPTURE set to 1. These sessions start with the existing shader cache and produce an updated version.

Shader cache size limits

Shader caches smaller than 10 KB or larger than 4 GB (uncompressed) are rejected.

Shader cache workflow

When you generate a shader cache for an existing Amazon GameLift Streams application, all compatible associated stream groups automatically start using it.

To test a shader cache before it affects production sessions, we recommend this approach:

Shader cache replication

After a successful capture, Amazon GameLift Streams automatically makes the shader cache available in every active streaming location in the application's compatible associated stream groups. This replication process typically completes within a few minutes.

You can monitor replication progress using the ListApplicationShaderCaches API operation. The shader cache Status field indicates the aggregated status across all locations of the stream group. Possible statuses include the following.

When the status is READY, the shader cache is automatically applied to all new stream sessions for the application.

Newly provisioned stream capacity receives the shader cache immediately. Existing stream group capacity can take up to one hour to obtain the new shader cache.

Disabling shader cache consumption

By default, Amazon GameLift Streams downloads and applies the shader cache before launching the application. To disable this behavior for a specific session, set the following environment variable:

{
  "AdditionalEnvironmentVariables": {
    "GAMELIFT_STREAMS_PACKAGED_SHADER_CACHE_IGNORE": "1"
  }
}

To improve upon an existing shader cache, provide only GAMELIFT_STREAMS_PACKAGED_SHADER_CACHE_CAPTURE. To discard the existing cache and collect a completely new one, provide both GAMELIFT_STREAMS_PACKAGED_SHADER_CACHE_IGNORE and GAMELIFT_STREAMS_PACKAGED_SHADER_CACHE_CAPTURE.

Shader cache compatibility

You can associate an application with multiple stream groups. To find out which stream groups your application is currently associated with, use the GetApplication API operation and review the AssociatedStreamGroups field.

Not all associated stream groups are necessarily compatible with a collected shader cache. You can determine which associated stream groups are compatible by using the ListApplicationShaderCaches API operation. In its response, the AssociatedStreamGroups field contains only those associated stream groups that are compatible with the shader cache.

Graphics hardware and drivers determine how the system compiles shader programs. Because of this, caches are not transferable across different hardware and software configurations. With Amazon GameLift Streams, shader cache compatibility is determined by the properties of the stream group used during capture:

In practice, this means that a Amazon GameLift Streams shader cache has the following compatibility restrictions.

Amazon GameLift Streams automatically determines this compatibility and uses the collected shader cache only with compatible sessions.

Example: Different generation stream classes

Your application is associated with two stream groups:

The same shader cache is not compatible across these two different generation stream groups. To support both stream groups, generate a separate shader cache for each stream class.

Example: Different GPU driver versions

You have a stream group that uses the gen6n_high stream class, and have generated a shader cache for it. Later you create another stream group, still using the same stream class gen6n_high.

This new stream group now uses a different, more recent GPU driver version. By using ListApplicationShaderCaches, you find out that your new stream group is not listed under AssociatedStreamGroups. The existing shader cache is therefore not compatible with the new stream group. Generate a new shader cache by using the new stream group.

Troubleshooting shader cache issues