Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

CompositorEffect

实验性： The implementation may change as more of the rendering internals are exposed over time.

继承： Resource < RefCounted < Object

用于创建自定义渲染效果的资源。

描述

这种资源定义的是自定义渲染效果，可以通过视口的 Environment 应用到 Viewport 上。可以实现在渲染管道的给定阶段进行渲染期间调用的回调，并允许插入其他阶段。请注意，该回调是在渲染线程上执行的。CompositorEffect 是抽象基类，实现特定的渲染逻辑必须对该类进行扩展。

教程

属性

bool

access_resolved_color

bool

access_resolved_depth

EffectCallbackType

effect_callback_type

bool

enabled

bool

needs_motion_vectors

bool

needs_normal_roughness

bool

needs_separate_specular

方法

void

_render_callback(effect_callback_type: int, render_data: RenderData) virtual

枚举

enum EffectCallbackType: 🔗

EffectCallbackType EFFECT_CALLBACK_TYPE_PRE_OPAQUE = 0

回调在不透明渲染阶段之前调用，但在深度前置阶段之后（如果适用）。

EffectCallbackType EFFECT_CALLBACK_TYPE_POST_OPAQUE = 1

回调在不透明渲染阶段之后调用，但在渲染天空之前。

EffectCallbackType EFFECT_CALLBACK_TYPE_POST_SKY = 2

回调在渲染天空之后调用，但在创建后台缓冲之前（如果启用，则在次表面散射和/或屏幕空间反射之前）。

EffectCallbackType EFFECT_CALLBACK_TYPE_PRE_TRANSPARENT = 3

回调在透明渲染阶段之前调用，但在渲染天空和创建后台缓冲区之后。

EffectCallbackType EFFECT_CALLBACK_TYPE_POST_TRANSPARENT = 4

回调在透明渲染阶段之后调用，但在内置后期效果和输出到渲染目标之前。

EffectCallbackType EFFECT_CALLBACK_TYPE_MAX = 5

代表 EffectCallbackType 枚举的大小。

属性说明

bool access_resolved_color 🔗

  • void set_access_resolved_color(value: bool)

  • bool get_access_resolved_color()

如果为 true 并且启用了 MSAA，则会在执行该效果之前触发颜色缓冲的解析。

注意：要在 _render_callback() 中访问解析后的缓冲，请使用：

var render_scene_buffers = render_data.get_render_scene_buffers()
var color_buffer = render_scene_buffers.get_texture("render_buffers", "color")

bool access_resolved_depth 🔗

  • void set_access_resolved_depth(value: bool)

  • bool get_access_resolved_depth()

如果为 true 并且启用了 MSAA，则会在执行该效果之前触发深度缓冲的解析。

注意：要在 _render_callback() 中访问解析后的缓冲，请使用：

var render_scene_buffers = render_data.get_render_scene_buffers()
var depth_buffer = render_scene_buffers.get_texture("render_buffers", "depth")

EffectCallbackType effect_callback_type 🔗

实现的效果类型，决定在渲染的哪个阶段调用回调。

bool enabled 🔗

  • void set_enabled(value: bool)

  • bool get_enabled()

如果为 true，则该渲染效果会应用到所有相关视口。

bool needs_motion_vectors 🔗

  • void set_needs_motion_vectors(value: bool)

  • bool get_needs_motion_vectors()

如果为 true，则会在不透明渲染状态下触发运动向量的计算。

注意：要在 _render_callback() 中访问运动向量缓冲，请使用：

var render_scene_buffers = render_data.get_render_scene_buffers()
var motion_buffer = render_scene_buffers.get_velocity_texture()

bool needs_normal_roughness 🔗

  • void set_needs_normal_roughness(value: bool)

  • bool get_needs_normal_roughness()

如果为 true，则会在深度预阶段中输出法线和粗糙度数据，仅适用于 Forward+ 渲染器。

注意：在 _render_callback() 中访问粗糙度缓冲：

var render_scene_buffers = render_data.get_render_scene_buffers()
var roughness_buffer = render_scene_buffers.get_texture("forward_clustered", "normal_roughness")

原始的法线和粗糙度缓冲使用优化格式存储，与空间着色器中的格式不同。对缓冲采样时必须应用转换函数。请使用从这里复制的函数：

vec4 normal_roughness_compatibility(vec4 p_normal_roughness) {
    float roughness = p_normal_roughness.w;
    if (roughness > 0.5) {
        roughness = 1.0 - roughness;
    }
    roughness /= (127.0 / 255.0);
    return vec4(normalize(p_normal_roughness.xyz * 2.0 - 1.0) * 0.5 + 0.5, roughness);
}

bool needs_separate_specular 🔗

  • void set_needs_separate_specular(value: bool)

  • bool get_needs_separate_specular()

如果为 true，则会触发镜面反射数据渲染至独立缓冲，在应用效果后进行混合，仅适用于 Forward+ 渲染器。

方法说明

void _render_callback(effect_callback_type: int, render_data: RenderData) virtual 🔗

请使用自定义的渲染代码实现该方法。effect_callback_type 应当与 effect_callback_type 中指定的效果回调类型一致。可以通过 render_data 访问渲染状态，这个状态只有在渲染时有效，不应该存储。