Version: 2023.1
Single-pass stereo rendering for Android
Testing and debugging

Framebuffer orientation

If your application’s framebuffer orientation doesn’t match the device’s native display orientation (portrait, for most devices), Android rotates the application’s framebuffer to match the device’s display every frame. Depending on the device’s hardware capabilities, this additional rotation can negatively affect performance. If your application uses the Vulkan Graphics API and the device supports Vulkan, Unity can apply this rotation during rendering which reduces the performance impact of the rotation. This is called pre-rotation.

Using pre-rotation in Unity

To make Unity apply pre-rotation, you can use C# scripts or the Unity editor:

How Unity applies pre-rotation

Unity applies pre-rotation when it renders directly to the device’s backbuffer, not when it renders to a Render Texture. To apply the rotation, Unity modifies the projection matrix which affects the UNITY_MATRIX_MVP and UNITY_MATRIX_P Built-in shader variables. This means that Unity applies the rotation in the vertex shader.

Using pre-rotation doesn’t affect the behavior of Unity’s C# API. For example, you can still use Screen.width to access the width of the screen. The same applies to viewports and scissor rects. Unity adjusts these as needed, and also handles readback operations from the backbuffer such as Grab Pass, ReadPixels, or Screenshot.

Unity provides utility macros to handle special cases in shaders (for more information, see the Limitations section below).

仅当以下所有条件都为真时才定义宏 UNITY_PRETRANSFORM_TO_DISPLAY_ORIENTATION(否则,未定义):

  • preTransform 在播放器设置中启用
  • 平台设置为 Android
  • 图形 API 设置为 Vulkan

UNITY_DISPLAY_ORIENTATION_PRETRANSFORM 是一个常量,设置为当前 preTransform 旋转。它的值是以下之一:

  • UNITY_DISPLAY_ORIENTATION_PRETRANSFORM_0
  • UNITY_DISPLAY_ORIENTATION_PRETRANSFORM_90
  • UNITY_DISPLAY_ORIENTATION_PRETRANSFORM_180
  • UNITY_DISPLAY_ORIENTATION_PRETRANSFORM_270

如果 UNITY_PRETRANSFORM_TO_DISPLAY_ORIENTATION 未定义,或者当渲染到渲染纹理时,UNITY_DISPLAY_ORIENTATION_PRETRANSFORM 的值是 UNITY_DISPLAY_ORIENTATION_0。

UNITY_DISPLAY_ORIENTATION_PRETRANSFORM is translated into a Vulkan specialization constant, which makes it efficient to use in if or switch statements.

限制

在以下情况下,如果启用 preTransform,则 Unity 项目可能需要额外修改,然后才能使用:

  • 不使用 Unity 投影矩阵的着色器
  • 依赖于片元着色器中当前像素位置的着色器 (SV_Position)
  • 使用屏幕空间导数(ddx、ddy)的着色器
  • 使用 Vulkan 交换链图像的原生渲染插件可能需要修改
  • 在 MRT 设置中通过 Unity RenderPass API 同时使用后备缓冲区与其他渲染纹理

这些情况仅适用于直接渲染到后备缓冲区时。

其他资源

Single-pass stereo rendering for Android
Testing and debugging