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...

캔버스아이템 셰이더

CanvasItem 셰이더는 Godot에서 모든 2D 요소를 그리는 데 사용됩니다. 여기에는 CanvasItems에서 상속되는 모든 노드 및 모든 GUI 요소가 포함됩니다.

CanvasItem 셰이더에는 :ref:`Spatial shaders<doc_spatial_shader>`보다 내장 변수와 기능이 적지만 정점, 조각, 라이트 프로세서 기능으로 동일한 기본 구조를 유지합니다.

렌더러 모드

렌더링 모드	설명
블렌드_믹스	혼합 혼합 모드(알파는 투명도), 기본값.
블렌드_추가	덧셈 블렌드 모드.
blend_sub	빼기 블렌드 모드.
blend_mul	곱셈 블렌드 모드.
blend_premul_alpha	미리 곱해진 알파 블렌드 모드.
blend_disabled	블렌딩을 비활성화하면 값(알파 포함)이 그대로 기록됩니다.
음영되지 않음	결과는 알베도입니다. 머티리얼에는 조명/음영이 발생하지 않습니다.
가벼운 전용	라이트 패스만 그립니다.
skip_vertex_transform	VERTEX``는 ``vertex() 함수에서 수동으로 변환해야 합니다.
world_vertex_coords	``VERTEX``는 로컬이 아닌 세계 좌표에서 수정됩니다.

Built-In(내장)

``in``로 표시된 값은 읽기 전용입니다. ``out``로 표시된 값은 선택적으로 쓸 수 있으며 반드시 합리적인 값을 포함하지는 않습니다. ``inout``로 표시된 값은 적절한 기본값을 제공하며 선택적으로 쓸 수 있습니다. 샘플러는 기록할 수 없으므로 표시되지 않습니다.

모든 내장 기능을 모든 처리 기능에서 사용할 수 있는 것은 아닙니다. fragment() 함수에서 내장된 정점에 액세스하려면 varying <doc_shading_언어_varyings>`을 사용할 수 있습니다. ``light()` 함수에서 내장된 조각에 액세스하는 경우에도 동일하게 적용됩니다.

벡터 내장 타입

사용자 정의 기능을 포함하여 전역 내장 기능을 어디에서나 사용할 수 있습니다.

내장	설명
부동 소수점 TIME	엔진이 시작된 이후의 전역 시간(초)입니다. 3,600``초마다 반복됩니다(:ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>` 설정으로 변경 가능). :ref:`time_scale<class_Engine_property_time_scale>`의 영향을 받지만 일시 중지의 영향을 받지는 않습니다. 시간 척도의 영향을 받지 않는 ``TIME 변수가 필요한 경우 고유한 :ref:`global shader uniform<doc_shading_language_global_uniforms>`를 추가하고 각 프레임을 업데이트하세요.
부동 소수점 PI	PI 상수(3.141592). 원의 지름과 반 바퀴의 라디안 수에 대한 원주 비율입니다.
부동 TAU	TAU 상수(6.283185). PI * 2 및 1회전의 라디안 수와 동일합니다.
부동 E	E 상수(2.718281). 자연로그의 밑이 되는 오일러 수.

벡터 내장 타입

정점 데이터(VERTEX)는 로컬 공간(Node2D의 원점을 기준으로 한 픽셀 좌표)에 표시됩니다. 기록되지 않으면 이러한 값은 수정되지 않고 그대로 전달됩니다.

사용자는 내장 모델을 비활성화하고(세계를 화면으로 변환하고 투영은 나중에 발생함) 다음 코드를 사용하여 수동으로 수행할 수 있습니다.

shader_type canvas_item;
render_mode skip_vertex_transform;

void vertex() {

    VERTEX = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
}

UV 및 COLOR``와 같은 다른 내장 기능도 수정되지 않으면 ``fragment() 함수로 전달됩니다.

인스턴스화의 경우 INSTANCE_CUSTOM 변수에는 인스턴스 사용자 정의 데이터가 포함됩니다. 입자를 사용할 때 이 정보는 일반적으로 다음과 같습니다.

• x: 라디안 단위의 회전 각도입니다.

• y: 수명 동안의 단계(0.0``~``1.0).

• z: 애니메이션 프레임.

내장	설명
mat4 MODEL_MATRIX	로컬 공간에서 월드 공간으로 변환됩니다. 월드 공간은 에디터에서 일반적으로 사용하는 좌표입니다.
mat4 CANVAS_MATRIX	월드 공간을 캔버스 공간으로 변환합니다. 캔버스 공간에서 원점은 화면의 왼쪽 위 모서리이며 좌표 범위는 ``(0.0, 0.0)``에서 뷰포트 크기까지입니다.
mat4 SCREEN_MATRIX	캔버스 공간을 클립 공간으로 변환합니다. 클립 공간 좌표 범위는 ``(-1.0, -1.0)``에서 ``(1.0, 1.0).``까지입니다.
int INSTANCE_ID	인스턴스화를 위한 인스턴스 ID입니다.
vec4 **INSTANCE_CUSTOM**에서	인스턴스 사용자 정의 데이터.
bool **AT_LIGHT_PASS**에서	if x else
vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of the default 2D texture. For a Sprite2D with a texture of size 64×32 pixels, TEXTURE_PIXEL_SIZE = vec2(1.0 / 64.0, 1.0 / 32.0).
inout vec2 VERTEX	이 기능은 항상 전반적인 좌표에 적용됩니다.
int VERTEX_ID	정점 버퍼에 있는 현재 정점의 인덱스입니다.
inout vec2 UV	정규화된 텍스처 좌표. 범위는 ``0.0``부터 ``1.0``까지입니다.
inout vec4 색상	CanvasItem의 :ref:`modulate<class_CanvasItem_property_modulate>`를 CanvasItem의 :ref:`self_modulate<class_CanvasItem_property_self_modulate>`로 곱한 정점 프리미티브의 색상입니다.
부동 소수점 POINT_SIZE	포인트 그리기를 위한 포인트 크기입니다.
vec4 **CUSTOM0**에서	정점 기본 요소의 사용자 정의 값입니다.
vec4에서 커스텀1	정점 기본 요소의 사용자 정의 값입니다.

프래그먼트 내장

색상과 질감

내장 변수 ``COLOR``는 몇 가지 용도로 사용됩니다.

• vertex() 함수에서 ``COLOR``에는 CanvasItem의 :ref:`modulate<class_CanvasItem_property_modulate>`와 CanvasItem의 :ref:`self_modulate<class_CanvasItem_property_self_modulate>`를 곱한 정점 기본 요소의 색상이 포함됩니다.

• fragment() 함수에서 입력 값 ``COLOR``는 동일한 값에 기본 ``TEXTURE``(있는 경우)의 색상을 곱한 값입니다.

• fragment() 함수에서는 ``COLOR``도 최종 출력입니다.

특정 노드(예: Sprite2D)는 기본적으로 텍스처를 표시합니다(예: texture). 사용자 정의 fragment() 함수를 사용할 때 이 텍스처를 샘플링하는 방법에 대한 몇 가지 옵션이 있습니다.

정점 ``COLOR``를 무시하고 기본 텍스처의 내용만 읽으려면:

void fragment() {
  COLOR = texture(TEXTURE, UV);
}

정점 ``COLOR``를 곱한 기본 텍스처의 내용을 읽으려면:

void fragment() {
  // Equivalent to an empty fragment() function, since COLOR is also the output variable.
  COLOR = COLOR;
}

``fragment()``에서 정점 ``COLOR``만 읽으려면 기본 텍스처를 무시하고 ``COLOR``를 가변으로 전달한 다음 ``fragment()``에서 읽어야 합니다.

varying vec4 vertex_color;
void vertex() {
  vertex_color = COLOR;
}
void fragment() {
  COLOR = vertex_color;
}

일반

마찬가지로, 노멀 맵이 CanvasTexture <class_CanvasTexture>`에서 사용된다면 Godot는 기본적으로 이를 사용하고 내장된 ``NORMAL` 변수에 그 값을 할당합니다. 3D용 노멀 맵을 사용하는 경우, 노멀 맵이 반전되어 나타납니다. 셰이더에서 사용하려면 NORMAL_MAP 속성에 할당해야 합니다. Godot는 2D에서 사용하기 위해 변환하고 ``NORMAL``를 덮어쓰는 작업을 처리할 것입니다.

NORMAL_MAP = texture(NORMAL_TEXTURE, UV).rgb;

내장	설명
vec4에서 FRAGCOORD	Coordinate of pixel center. In screen space. xy specifies position in viewport. Upper-left of the viewport is the origin, (0.0, 0.0). Bottom-right of the viewport is (1.0, 1.0).
vec2에서 SCREEN_PIXEL_SIZE	개별 픽셀의 크기. 해상도의 역수와 같습니다.
vec4 **REGION_RECT**에서	Visible area of the sprite region in format (x, y, width, height). Varies according to Sprite2D's region_enabled property. Values are normalized; for example, a 600×400 region on a 1000×800 texture with a 100×100 offset would be vec4(0.1, 0.125, 0.6, 0.5). Values may exceed the 0.0 to 1.0 range if the X/Y offset is negative, or if the size exceeds the texture's size.
vec2 **POINT_COORD**에서	Coordinate for drawing points in the 0.0 to 1.0 range.
Sampler2D 텍스처	기본 2D 텍스처.
vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of the default 2D texture. For a Sprite2D with a texture of size 64×32 pixels, TEXTURE_PIXEL_SIZE = vec2(1.0 / 64.0, 1.0 / 32.0).
bool **AT_LIGHT_PASS**에서	if x else
Sampler2D SPECULAR_SHININESS_TEXTURE	이 개체의 반사광 광택 텍스처입니다.
vec4에서 SPECULAR_SHININESS	텍스처에서 샘플링된 반사광 광택 색상입니다.
vec2 **UV**에서	vertex() 함수의 UV. 영역이 활성화된 Sprite2D의 경우 전체 텍스처가 샘플링됩니다. Sprite2D의 속성에 정의된 영역만 샘플링하려면 대신 ``REGION_RECT``를 사용하세요.
vec2에서 SCREEN_UV	현재 픽셀의 스크린 UV 좌표입니다.
샘플러2D SCREEN_TEXTURE	Godot 4에서는 제거되었습니다. 대신 ``sampler2D``와 ``hint_screen_texture``를 사용하세요.
inout vec3 정상	``NORMAL_TEXTURE``에서 일반 읽기입니다. 쓰기 가능.
샘플러2D NORMAL_TEXTURE	기본 2D 일반 텍스처.
out vec3 NORMAL_MAP	2D에서 사용하기 위해 3D용 노멀 맵을 구성합니다. 사용하는 경우 ``NORMAL``를 재정의합니다.
부동 소수점 NORMAL_MAP_DEPTH	노멀 매핑.
inout vec2 VERTEX	화면 공간의 픽셀 위치입니다.
inout vec2 SHADOW_VERTEX	``VERTEX``와 동일하지만 그림자를 변경하도록 작성할 수 있습니다.
inout vec3 LIGHT_VERTEX	``VERTEX``와 동일하지만 조명을 변경하도록 작성할 수 있습니다. Z 구성요소는 높이를 나타냅니다.
inout vec4 색상	vertex() 함수의 COLOR``에 ``TEXTURE 색상을 곱합니다. 색상 값도 출력합니다.

기본 내장 타입

라이트 프로세서 기능은 Godot 3.x와 Godot 4.x에서 다르게 작동합니다. Godot 4.x에서 모든 라이팅은 정규 드로우 패스 중에 이루어집니다. 즉, Godot는 더 이상 각 조명에 대해 개체를 다시 그리지 않습니다.

light() 기능을 실행하지 않으려면 unshaded 렌더링 모드를 사용하십시오. 객체에 대한 조명의 영향만 보려면 light_only 렌더링 모드를 사용하십시오. 이는 물체가 빛으로 덮인 곳에서만 보이도록 하려는 경우에 유용할 수 있습니다.

light() 함수를 정의하면 조명 기능이 비어 있어도 내장 조명 기능이 대체됩니다.

다음은 CanvasItem의 노멀 맵을 고려하는 조명 셰이더의 예입니다.

void light() {
  float cNdotL = max(0.0, dot(NORMAL, LIGHT_DIRECTION));
  LIGHT = vec4(LIGHT_COLOR.rgb * COLOR.rgb * LIGHT_ENERGY * cNdotL, LIGHT_COLOR.a);
}

내장	설명
vec4에서 FRAGCOORD	Coordinate of pixel center. In screen space. xy specifies position in viewport. Upper-left of the viewport is the origin, (0.0, 0.0). Bottom-right of the viewport is (1.0, 1.0).
vec3에서 정상	입력
vec4에서 컬러	색상을 입력합니다. 이는 fragment() 함수의 출력입니다.
vec2 **UV**에서	vertex() 함수의 UV는 fragment() 함수의 UV와 동일합니다.
Sampler2D 텍스처	CanvasItem에 사용 중인 현재 텍스처입니다.
vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of TEXTURE. For a Sprite2D with a TEXTURE of size 64×32 pixels, TEXTURE_PIXEL_SIZE = vec2(1.0 / 64.0, 1.0 / 32.0).
vec2에서 SCREEN_UV	현재 픽셀의 스크린 UV 좌표입니다.
vec2 **POINT_COORD**에서	포인트 스프라이트의 UV.
vec4에서 LIGHT_COLOR	class_Light2D`의 :ref:`Color. 조명이 :ref:`class_PointLight2D`인 경우 조명의 :ref:`texture<class_PointLight2D_property_texture>`를 곱합니다.
부동 LIGHT_ENERGY	class_Light2D`의 :ref:`Energy multiplier.
vec3 LIGHT_POSITION	화면 공간에서 :ref:`class_Light2D`의 위치입니다. :ref:`class_DirectionalLight2D`를 사용하는 경우 이는 항상 ``(0.0, 0.0, 0.0)``입니다.
vec3 LIGHT_DIRECTION	화면 공간에서 :ref:`class_Light2D`의 방향입니다.
부울 LIGHT_IS_DIRECTIONAL	이 패스가 :ref:`class_DirectionalLight2D`인 경우 ``true``입니다.
vec3 **LIGHT_VERTEX**에서	fragment() 함수에서 수정된 화면 공간의 픽셀 위치입니다.
inout vec4 빛	출력 로그
vec4에서 SPECULAR_SHININESS	물체의 질감에 설정된 반사광 광택입니다.
out vec4 SHADOW_MODULATE	이 지점에 드리워진 그림자에 이 색상을 곱합니다.

SDF 함수

자동으로 생성된 Signed Distance Field 텍스처를 샘플링하기 위해 구현된 몇 가지 추가 기능이 있습니다. 이러한 기능은 CanvasItem 셰이더의 fragment() 및 light() 기능에서 사용할 수 있습니다. 사용자 정의 함수는 지원되는 함수에서 호출되는 한 이를 사용할 수도 있습니다.

부호 있는 거리 필드는 SDF 충돌 속성이 활성화된(기본값) 씬에 있는 LightOccluder2D 노드에서 생성됩니다. 자세한 내용은 2D 조명 및 그림자 문서를 참조하세요.

함수	설명
float texture_sdf (vec2 sdf_pos)	SDF 텍스처 조회를 수행합니다.
vec2 texture_sdf_normal (vec2 sdf_pos)	SDF 텍스처에서 법선을 계산합니다.
vec2 sdf_to_screen_uv (vec2 sdf_pos)	탭으로 들여쓰도록 변환
vec2 screen_uv_to_sdf (vec2 uv)	탭으로 들여쓰도록 변환