engine/docs/en/graphics/postProcess/postProcess.mdx

---
order: 0
title: Post Process Overview
---

The post-processing system can "process" the results rendered by the camera.

<Comparison
  leftSrc="https://gw.alipayobjects.com/zos/OasisHub/3a50ed18-c2d4-4b33-a4e6-af79f2c273f8/2024-07-18%25252018.08.30.gif"
  leftText="OFF"
  rightSrc="https://gw.alipayobjects.com/zos/OasisHub/4bd5f985-1b82-4aca-b6fa-fd521aab8f57/2024-07-18%25252018.15.30.gif"
  rightText="ON"
/>

## Post-Processing Component

There are two modes for post-processing:

- Global Mode: Affects all cameras in the current scene.
- Local Mode: Only effective when the camera is within the collision range of the post-processing entity.

The post-processing component has the following properties to control effects, modes, blending distances, etc.:

| Property | Description |
| :-- | :-- |
| [isGlobal](/apis/core/#PostProcess-isGlobal) | Controls whether this post-processing component is in global or local mode. |
| [Blend Distance](/apis/core/#PostProcess-blendDistance) | In local mode, controls how close the camera must be to the collider before blending effects begins. |
| [Priority](/apis/core/#PostProcess-priority) | When there are multiple post-processing components in the scene, a higher priority means blending/overriding starts later. |
| [Layer](/apis/core/#PostProcess-layer) | Used with the camera's [post-processing mask](/apis/core/#Camera-postProcessMask) to determine which post-processing components are effective. |
| [Add Effect](/apis/core/#PostProcess-addEffect) | Adds post-processing effects. |

## Mixing rules

- In global mode, the mixing rules are based on the post-processing component with the highest priority.

- In local mode, it will start from the **mixing distance** of the camera from the collision body, and transition from the mixed value of the previous post-processing component to the value of the current post-processing component. If there is no previous one, the defined value of the post-processing effect will be used as the starting value.

For example, the intensity is defined as `0`, which is defined by [PostProcessEffectFloatParameter](/apis/core/#PostProcessEffectFloatParameter):

- PostProcessing Component 1: Global mode, intensity is `0.5`, after blending it is `0.5`

- PostProcessing Component 2: Local mode, intensity is `1`, the camera distance to the collider is half of the blend distance, after blending it is `mix( 0.5, 1, 1 - distance / blendDistance)` = `0.75`

<Callout type="info">
  If you want to customize post-processing, please refer to
  [Documentation](/en/docs/graphics/postProcess/customPostProcess/#3-blend-data)
</Callout>

## Using Post-Processing

### 1. Adding a Post-Processing Component

In the hierarchy panel, several modes for global and local post-processing are preset; simply select and add to use.

<Image src="https://gw.alipayobjects.com/zos/OasisHub/a6e9a327-1823-4dde-94a8-89bb4bf02e3a/2025-01-15%25252011.59.50.gif" />

Of course, you can also manually add post-processing components. Local mode needs to be used with colliders:

<Image src="https://gw.alipayobjects.com/zos/OasisHub/6eb3b8d5-27d1-419d-8bf6-65371861fb97/2025-01-15%25252014.51.12.gif" />

<Callout type="info">
  For specific post-processing effects configuration, please refer to the [Post-Processing Effects
  List](/en/docs/graphics/postProcess/effects)
</Callout>

### 2. Camera Switch

The camera preview area is controlled by the **Camera Component**. In the camera component, the following properties will also affect the post-processing effects:

| Property | Description |
| :-- | :-- |
| [Post-Processing Switch](/apis/core/#Camera-enablePostProcess) | Enables or disables the post-processing effects of the camera. |
| [HDR Switch](/apis/core/#Camera-enableHDR) | In HDR mode, allows output colors to be stored using floating-point numbers, providing a broader range of values for [bloom effects](/en/docs/graphics/postProcess/effects) and other scenarios. |
| [MSAA Configuration](/apis/core/#Camera-msaaSamples) | Adjusts the multi-sampling anti-aliasing settings to improve image quality, such as reducing jagged edges. |
| [Post-Processing Mask](/apis/core/#Camera-postProcessMask) | Works with the post-processing component's [layer](/apis/core/#PostProcess-layer) to determine which post-processing components are effective. |

<Callout type="info">
  For more camera configurations, refer to the [Camera Component](/en/docs/graphics/camera/component)
</Callout>

### 3. Viewport Switch

In addition to the camera preview area, the viewport can also display post-processing effects. The camera in the viewport is independent but has post-processing configurations similar to the camera component.

<Callout type="warning">
  The switch in the viewport only affects the view window and does not impact the actual effect exported in the project.
</Callout>

<Image src="https://gw.alipayobjects.com/zos/OasisHub/e3c55184-f51c-4a7a-9a12-ad490774dc26/image-20250115151324628-20250115151336116.png" />


### 4. Pro code
```ts
// Get post-processing component
const postProcessComponent = entity.getComponent(PostProcess);

// Set properties for component
postProcessComponent.isGlobal = false;

// Get post-processing effect
const bloomEffect = postProcessComponent.getEffect(BloomEffect);

// You can also add post-processing effects manually
const bloomEffect = postProcessComponent.addEffect(BloomEffect);

// Setting properties of post-processing effects
bloomEffect.intensity.value = 1;
bloomEffect.threshold.value = 0.5;
```
<Callout type="info">
  For specific post-processing effects configuration, please refer to the [Post-Processing Effects
  List](/en/docs/graphics/postProcess/effects)
</Callout>


## Post-processing mask
As mentioned above, the post-processing component has a property called [layer](/apis/core/#PostProcess-layer). When there are multiple post-processing components in the scene, you can use it with the camera's [post-processing mask](/apis/core/#Camera-postProcessMask) to determine the effective post-processing component;
This method is only used to determine the source of data blend. If you only want certain entities to have post-processing, you can use the multi-scene solution and add the Entity that does not need post-processing to another Scene.

<Image src="https://gw.alipayobjects.com/zos/OasisHub/ad36f45d-8e15-4fab-8ce9-dc0641a812d4/image-20250407183538658.png" />

<Image src="https://gw.alipayobjects.com/zos/OasisHub/d578cdb0-5f96-496b-91d6-8fedca938a3b/image-20250407183445964.png" />


## Best Practices

- Regarding the `HDR` switch in the camera, if the majority of pixels in the scene do not exceed 1 (e.g., no HDR textures used), avoid enabling HDR. When enabled, the engine first renders to a `R11G11B10_UFloat` format RenderTarget before rendering to the screen, incurring performance overhead.
- Regarding the `MSAA` option in the camera, only adjust this value when post-processing is enabled and strict on anti-aliasing performance. The higher the value, the greater the performance overhead.
- In bloom effects, `Down Scale` defaults to `Half`, meaning the initial downsampled resolution is half that of the canvas. If high precision is not required, switch to `Quarter`, saving to a quarter of the canvas.
- In tone mapping effects, while `ACES` offers better color contrast and saturation, it is computationally complex and may cause significant frame drops on low-end devices. Consider using `Neutral` as an alternative.