Screen.SetMSAASamples

Description

Switches the number of MSAA samples of the Unity swapchain.

The value indicates the number of samples per pixel. Valid values are 0 (use the Quality settings value), 1, 2, 4, and 8. If the graphics API does not support the value you provide, it uses the next highest supported value. This function is a low level method that does not affect the rendering state or settings. It sets the format of the allocated system render target. Unity does not change the number of samples immediately. The exact time when the change happens is platform dependent. Calling this method early in the frame might have an effect during this frame on some platforms, but might defer to the next frame on other platforms where the switch is done at the end of the frame.

This function is only available when using a scriptable render pipeline and will log an error when used with built-in. It enables the render pipeline internals to control the system rendertarget from script. Setting this from script will not enable MSAA on the render pipeline. Please see the renderpipeline documention for information on how to enable MSAA rendering for the renderpipeline in-use.

If you are writing your own renderpipeline it is likely you want to do your own resolving as part of your renderpipeline's post processing chain. In that case, for best performance, it is recommended to set the number of samples to '1' to disable MSAA on the system render target. If the value is set to 0 (default) the behaviour is identical to built-in, i.e. it uses the msaa sample count saved in the quality settings and Unity may allocate a MSAA rendertarget that is not needed since your renderpipeline already resolves as part of it's post processing.

The example sketches how a renderpipeline may use SetMSAASamples in combination with it's own MSAA settings to ensure the system render target is properly configured for it's use case:

using UnityEngine;
using UnityEngine.Rendering;

[CreateAssetMenu(menuName = "MyRenderPipeline/Create New Pipeline Asset")]
public class MyRenderPipelineAsset : RenderPipelineAsset
{
    public int msaaSamples = 1;
    public bool directToScreen = false;

    protected override RenderPipeline CreatePipeline()
    {
        return new MyRenderPipeline(this);
    }
}

public class MyRenderPipeline : RenderPipeline
{
    MyRenderPipelineAsset asset;

    public MyRenderPipeline(MyRenderPipelineAsset asset)
    {
        this.asset = asset;
        if (asset.directToScreen)
        {
            Screen.SetMSAASamples(asset.msaaSamples);
        }
        else
        {
            Screen.SetMSAASamples(1);
        }
    }

    protected override void Render(ScriptableRenderContext context, Camera[] cameras)
    {
        // Render frame, culling shadow maps ...

        // Final output to screen
        if (asset.directToScreen)
        {
            // Render geometry directly to system buffer no post processing is possible
            // the system provies the MSAA resolve as part of the final screen blit or desktop compositor
        }
        else
        {
            // Post processing resolves MSAA and eventually writes single sample data to the sceen
        }
    }
}