CustomMaterial QML Type

모델에 음영을 적용하는 데 사용되는 사용자 정의 재질을 생성하기 위한 기본 구성 요소. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• alwaysDirty : bool
• destinationAlphaBlend : enumeration (since 6.7)
• destinationBlend : enumeration
• fragmentShader : url
• lineWidth : real
• shadingMode : enumeration
• sourceAlphaBlend : enumeration (since 6.7)
• sourceBlend : enumeration
• vertexShader : url

상세 설명

사용자 정의 머티리얼을 사용하면 머티리얼에 사용자 정의 셰이더 코드를 적용할 수 있어, 그래픽 셰이더 수준에서 프로그래밍이 가능해집니다. 버텍스 셰이더, 프래그먼트 셰이더 또는 둘 다를 지정할 수 있습니다. vertexShader 및 fragmentShader 속성은 셰이더 스니펫이 포함된 파일을 참조하는 URL이며, ShaderEffect 또는 Image.source 과 매우 유사하게 작동합니다. 사용자 정의 머티리얼에서는 file 및 qrc 스키마만 지원됩니다. 또한 file 스키마를 생략하여 편리한 방식으로 상대 경로를 지정할 수도 있습니다. 이러한 경로는 컴포넌트( .qml 파일)의 위치를 기준으로 해석됩니다.

사용자 정의 머티리얼에 대한 시작 가이드는 ‘프로그래밍 가능한 머티리얼, 이펙트, 지오메트리 및 텍스처 데이터’ 페이지를 참조하십시오.

소개

동일한 씬의 다음 두 버전을 살펴보십시오. 왼쪽에서 원통은 내장된 비프로그래밍 가능 머티리얼을 사용하고 있습니다. 이러한 머티리얼은 다양한 속성을 통해 구성할 수 있지만, 내부적으로 생성되는 셰이더에 대해서는 추가적인 제어 권한이 주어지지 않습니다. 오른쪽에서는 동일한 원기둥이 애플리케이션에서 제공하는 버텍스 및 프래그먼트 셰이더 스니펫을 참조하는 CustomMaterial과 연결되어 있습니다. 이를 통해 버텍스 셰이더에 애플리케이션에 특화된 사용자 정의 로직을 삽입하여 지오메트리를 변환하고, 프래그먼트 셰이더에서 특정 색상 속성을 사용자 정의 방식으로 결정할 수 있습니다. 이는 ‘ shaded ’ 사용자 정의 머티리얼이므로, 원통은 여전히 평소와 같이 씬의 조명에 참여합니다.

View3D {
    anchors.fill: parent
    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, 0, 600)
    }
    camera: camera
    DirectionalLight {
        position: Qt.vector3d(-500, 500, -100)
        color: Qt.rgba(0.2, 0.2, 0.2, 1.0)
        ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    }
    Model {
        source: "#Cylinder"
        eulerRotation: Qt.vector3d(30, 30, 0)
        scale: Qt.vector3d(1.5, 1.5, 1.5)
        materials: [
            DefaultMaterial {
                diffuseColor: Qt.rgba(0, 1, 0, 1)
            }
        ]
    }
}

View3D {
    anchors.fill: parent
    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, 0, 600)
    }
    camera: camera
    DirectionalLight {
        position: Qt.vector3d(-500, 500, -100)
        color: Qt.rgba(0.2, 0.2, 0.2, 1.0)
        ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    }
    Model {
        source: "#Cylinder"
        eulerRotation: Qt.vector3d(30, 30, 0)
        scale: Qt.vector3d(1.5, 1.5, 1.5)
        materials: [
            CustomMaterial {
                vertexShader: "material.vert"
                fragmentShader: "material.frag"
                property real uTime
                property real uAmplitude: 50
                NumberAnimation on uTime { from: 0; to: 100; duration: 10000; loops: -1 }
            }
        ]
    }
}

material.vert 와 material.frag 에 있는 셰이더 스니펫이 다음과 같다고 가정해 봅시다:

void MAIN()
{
    VERTEX.x += sin(uTime + VERTEX.y) * uAmplitude;
}

void MAIN()
{
    BASE_COLOR = vec4(0.0, 1.0, 0.0, 1.0);
}

uTime 와 uAmplitude 가 CustomMaterial 요소의 속성이라는 점에 주목하세요. 이 속성들은 값을 변경하거나 정상적으로 애니메이션을 적용할 수 있으며, 개발자가 별도의 조치를 취하지 않아도 해당 값이 셰이더에 자동으로 노출됩니다.

그 결과, 정점들이 애니메이션되는 원통이 생성됩니다:

두 가지 유형의 커스텀 머티리얼

사용자 정의 머티리얼에는 두 가지 주요 유형이 있습니다. 이는 ` shadingMode ` 속성으로 지정됩니다. ` unshaded ` 사용자 정의 머티리얼의 경우, 프래그먼트 셰이더는 장면 내의 조명, 라이트 프로브, 그림자를 무시하고 단일 ` vec4 ` 색상을 출력합니다. ` shaded ` 머티리얼의 경우, 셰이더는 특정 함수를 구현하고 내장 변수를 사용하여 조명 및 그림자의 영향을 고려해야 합니다.

일반적으로 기본 선택 사항은 셰이디드 머티리얼이며, 이는 ` shadingMode ` 속성의 기본값에 반영되어 있습니다. 이는 정점이나 지오메트리에서 들어오는 기타 데이터를 변환해야 하거나, ` BASE_COLOR ` 또는 ` EMISSIVE_COLOR `과 같은 값을 사용자 정의 방식으로(예: ` SCREEN_TEXTURE ` 또는 ` DEPTH_TEXTURE`을 샘플링하여) 결정해야 하면서도, 여전히 씬의 조명 및 그림자 기여도를 수신해야 하는 머티리얼에 적합합니다. 또한, 이러한 머티리얼은 방향광, 점광 및 기타 광원의 기여도를 계산하는 데 사용되는 방정식을 재정의하고 재구현할 수도 있습니다. 표준 머티리얼이 제공하는 조명과 같은 기능을 구현하기 위해, 애플리케이션에서 제공하는 셰이더 스니펫은 내부적으로 Qt Quick 3D 엔진에 의해 대폭 수정됩니다.

언셰이디드(Unshaded) 머티리얼은 오브젝트의 외관이 전적으로 사용자 정의 셰이더 코드에 의해 결정될 때 유용합니다. 이러한 머티리얼에 대한 셰이더는 엔진에 의해 최소한의 추가 처리만 이루어지므로, 최종 프래그먼트 색상을 결정하는 것은 전적으로 셰이더에 달려 있습니다. 이는 더 큰 자유도를 제공하지만, 조명과 같은 씬의 다른 요소들과 통합할 수 있는 가능성은 제한합니다.

셰이더에 데이터 노출하기

CustomMaterial의 동적 속성은 QML 및 Qt Quick 기능을 사용하여 변경 및 애니메이션 처리할 수 있으며, 해당 값은 셰이더에 자동으로 노출됩니다. 이는 실제로 ShaderEffect 와 매우 유사합니다. 다음 목록은 속성이 어떻게 매핑되는지 보여줍니다:

• bool, int, real -> bool, int, float
• QColor, color → vec4이며, QML에 지정된 색상 값이 sRGB 색상 공간을 가정할 때 색상은 선형(linear)으로 변환됩니다. "green" 과 같은 내장 Qt 색상도 sRGB 색상 공간을 따르며, DefaultMaterial 및 PrincipledMaterial 의 모든 색상 속성에 대해서도 동일한 변환이 수행되므로, CustomMaterial의 이러한 동작은 이와 일치합니다. Qt Quick 와 달리, Qt Quick 3D 의 경우 3D 씬에 일반적으로 톤 매핑이 수행되므로 선형화 처리가 필수적입니다.
• QRect, QRectF, rect -> vec4
• QPoint, QPointF, point, QSize, QSizeF, size -> vec2
• QVector2D, vector2d -> vec2
• QVector3D, vector3d -> vec3
• QVector4D, vector4d -> vec4
• QMatrix4x4, matrix4x4 -> mat4
• QQuaternion, quaternion -> vec4, 스칼라 값은 w
• TextureInput -> sampler2D 또는 samplerCube가 됩니다. 이는 TextureInput 의 텍스처 속성에서 Texture 또는 CubeMapTexture 중 어느 것이 사용되는지에 따라 달라집니다. enabled 속성을 false로 설정하면 셰이더에 더미 텍스처가 노출되는데, 이는 셰이더가 여전히 작동하지만 불투명한 검은색 이미지 콘텐츠가 포함된 텍스처를 샘플링하게 됨을 의미합니다. 샘플러에 대한 속성은 항상 TextureInput 객체를 참조해야 하며, Texture 를 직접 참조해서는 안 된다는 점에 유의하십시오. Texture 의 속성 중 소스(source), 타일링(tiling), 필터링(filtering)과 관련된 속성만이 사용자 정의 머티리얼에서 암시적으로 고려되며, 나머지(예: UV 변환)는 사용자 정의 셰이더가 적절하다고 판단하는 대로 구현해야 합니다.

셰이딩이 적용되지 않은 사용자 정의 머티리얼

다음은 unshaded 사용자 정의 머티리얼의 예시입니다.

CustomMaterial {
    // These properties are automatically exposed to the shaders
    property real time: 0.0
    property real amplitude: 5.0
    property real alpha: 1.0
    property TextureInput tex: TextureInput {
        enabled: true
        texture: Texture { source: "image.png" }
    }

    shadingMode: CustomMaterial.Unshaded
    sourceBlend: alpha < 1.0 ? CustomMaterial.SrcAlpha : CustomMaterial.NoBlend
    destinationBlend: alpha < 1.0 ? CustomMaterial.OneMinusSrcAlpha : CustomMaterial.NoBlend
    cullMode: CustomMaterial.BackFaceCulling

    vertexShader: "customshader.vert"
    fragmentShader: "customshader.frag"
}

위의 예제를 바탕으로, unshaded 의 버텍스 및 프래그먼트 셰이더 코드 조각은 다음과 같이 작성될 수 있습니다. 최종 셰이더 코드를 조립할 때 Qt가 이를 처리하므로, 셰이더에서 유니폼이나 버텍스 입력을 선언하지 않으며, 또한 선언해서는 안 된다는 점에 유의하십시오.

VARYING vec3 pos;
VARYING vec2 texcoord;

void MAIN()
{
    pos = VERTEX;
    pos.x += sin(time * 4.0 + pos.y) * amplitude;
    texcoord = UV0;
    POSITION = MODELVIEWPROJECTION_MATRIX * vec4(pos, 1.0);
}

VARYING vec3 pos;
VARYING vec2 texcoord;

void MAIN()
{
    vec4 c = texture(tex, texcoord);
    FRAGCOLOR = vec4(pos.x * 0.02, pos.y * 0.02, pos.z * 0.02, alpha) * c;
}

다음과 같은 대문자 특수 키워드를 사용할 수 있습니다:

• MAIN -> 버텍스 또는 프래그먼트 셰이더 스니펫의 진입점 이름은 반드시 MAIN 이어야 합니다. 쉐이딩이 적용되지 않은 사용자 정의 머티리얼의 셰이더 스니펫에서는 이 함수를 반드시 제공해야 합니다.
• VARYING -> 버텍스 셰이더의 출력 또는 프래그먼트 셰이더의 입력을 선언합니다.
• POSITION -> vec4, 버텍스 셰이더의 출력
• FRAGCOLOR -> vec4, 프래그먼트 셰이더의 출력. 셰이딩이 적용되지 않은 사용자 정의 머티리얼에서만 사용할 수 있습니다.
• VERTEX -> vec3, 버텍스 셰이더 내의 버텍스 위치입니다.
• NORMAL -> vec3, 버텍스 셰이더의 버텍스 법선입니다. 관련 모델의 메시가 법선을 제공하지 않는 경우, 값은 vec3(0.0)입니다.
• UV0 -> vec2, 버텍스 셰이더의 첫 번째 텍스처 좌표 세트입니다. 관련 모델의 메시가 텍스처 좌표를 제공하지 않는 경우, 값은 vec2(0.0)입니다.
• UV1 -> vec2, 버텍스 셰이더에서 두 번째 텍스처 좌표 세트입니다. 관련 모델의 메시가 두 번째 텍스처 좌표 세트를 제공하지 않는 경우, 값은 vec2(0.0)입니다.
• COLOR -> vec4, 정점 셰이더의 정점 색상입니다. 관련 모델의 메시가 정점별 색상을 제공하지 않는 경우, 값은 vec4(1.0)입니다.
• TANGENT -> vec3, 버텍스 셰이더의 탄젠트입니다. 관련 모델의 메시가 탄젠트 데이터를 제공하지 않는 경우, 값은 vec3(0.0)입니다.
• BINORMAL -> vec3, 버텍스 셰이더의 바이노멀. 관련 모델의 메시가 바이노멀 데이터를 제공하지 않는 경우, 값은 vec3(0.0)입니다.
• JOINTS -> ivec4, 버텍스 셰이더의 조인트 인덱스. 관련 모델의 메시가 조인트 인덱스 데이터를 제공하지 않는 경우, 값은 ivec4(0)입니다.
• WEIGHTS -> vec4, 버텍스 셰이더의 조인트 가중치. 관련 모델의 메시가 조인트 가중치 데이터를 제공하지 않는 경우, 값은 vec4(0.0)입니다.
• MORPH_POSITION(n) -> vec3, 버텍스 셰이더 내의 n+1번째모프 타겟 위치. 관련 모델이 적절한 데이터를 제공해야 합니다.
• MORPH_NORMAL(n) -> vec3, 버텍스 셰이더에서 n+1번째모프 타깃 법선입니다. 관련 모델은 적절한 데이터를 제공해야 합니다.
• MORPH_TANGENT(n) -> vec3, 버텍스 셰이더에서 n+1번째모프 타깃 접선 벡터입니다. 관련 모델이 적절한 데이터를 제공해야 합니다.
• MORPH_BINORMAL(n) -> vec3, 버텍스 셰이더에서 n+1번째모프 타겟 바이노멀입니다. 관련 모델은 적절한 데이터를 제공해야 합니다.
• MODELVIEWPROJECTION_MATRIX -> mat4, 모델-뷰-투영 행렬입니다. 투영 행렬은 항상 OpenGL 규약을 따르며, 실행 시 사용되는 그래픽 API에 따라 Y축 방향 및 클립 깊이에 대한 변환이 내장되어 있습니다.
• VIEWPROJECTION_MATRIX -> mat4, 뷰-투영 행렬
• PROJECTION_MATRIX -> mat4, 투영 행렬
• INVERSE_PROJECTION_MATRIX -> mat4, 역 투영 행렬
• VIEW_MATRIX -> mat4, 뷰(카메라) 행렬
• MODEL_MATRIX -> mat4, 모델(월드) 행렬
• NORMAL_MATRIX -> mat3, 법선 행렬 (모델 행렬의 왼쪽 상단 3x3 부분의 역행렬의 전치)
• BONE_TRANSFORMS -> mat4[], 모델의 본 매트릭스 배열
• BONE_NORMAL_TRANSFORMS -> mat3[], 모델의 본 법선 행렬 배열 (각 본 행렬의 왼쪽 상단 3x3 부분의 역행렬을 전치한 것)
• MORPH_WEIGHTS -> float[], 모프 가중치 배열. 관련 모델은 적절한 데이터를 제공해야 합니다. 안전을 위해 QT_MORPH_MAX_COUNT는 이 배열의 크기로 정의됩니다.
• CAMERA_POSITION -> vec3, 월드 공간에서의 카메라 위치
• CAMERA_DIRECTION -> vec3, 월드 공간에서의 카메라 방향 벡터
• CAMERA_PROPERTIES -> vec2, 카메라의 근점 및 원점 클립 값
• POINT_SIZE -> float, 버텍스 셰이더에서만 설정 가능. 점(point) 토폴로지를 가진 지오메트리를 렌더링할 때, 사용자 정의 버텍스 셰이더는 셰이딩 및 비셰이딩 사용자 정의 머티리얼 모두에서 이 값을 1.0 또는 다른 값으로 설정해야 합니다. 1 이외의 크기에 대한 지원에 대한 자세한 내용은 PrincipledMaterial::pointSize 를 참조하십시오.

셰이딩이 적용된 사용자 정의 머티리얼

shaded 소재 augments 는 PrincipledMaterial 에 의해 생성될 셰이더 코드를 포함합니다. 셰이딩되지 않은 소재는 정점 및 프래그먼트 셰이더 메인 함수에 대한 거의 모든 로직을 자체적으로 제공하여 조명, 그림자, 전역 조명 등에 대한 생성된 코드의 추가를 방지하는 반면, 셰이딩된 소재는 CustomMaterial이 PrincipledMaterial 인 것처럼 셰이더 생성이 정상적으로 이루어지도록 합니다. 버텍스 및 프래그먼트 셰이더 스니펫은 선택적 함수를 제공해야 하며, 이 함수들은 특정 시점에서 호출되어 조명 계산 및 최종 프래그먼트 색상 산출에 사용되는 색상 및 기타 값을 사용자 정의할 수 있게 해줍니다.

MAIN 함수 하나만 구현하는 대신, 셰이딩된 커스텀 머티리얼의 프래그먼트 셰이더는 여러 함수를 구현할 수 있습니다. MAIN 를 포함한 모든 함수는 셰이딩된 커스텀 머티리얼에서 선택적으로 구현할 수 있습니다. 빈 셰이더 스니펫을 사용하거나, 심지어 vertexShader 또는 fragmentShader 속성을 전혀 지정하지 않는 경우에도 완벽하게 유효합니다.

셰이딩된 사용자 정의 머티리얼의 버텍스 셰이더 스니펫

버텍스 셰이더 스니펫에서는 다음 함수들을 구현할 수 있습니다:

• void MAIN() 이 함수가 존재할 경우, 버텍스 셰이더의 vec4 출력인 ` POSITION`의 값을 설정하고, 선택적으로 ` VERTEX`, ` COLOR`, ` NORMAL`, ` UV0`, ` UV1`, ` TANGENT` , BINORMAL, JOINTS, 그리고 WEIGHTS. 쉐이딩되지 않은 머티리얼과는 달리, 수정된 값이 이후 생성되는 나머지 셰이더 코드에서 반영되기 때문에 이 변수들에 값을 기록하는 것이 의미가 있습니다(반면 쉐이딩되지 않은 머티리얼의 경우 추가 셰이더 코드가 생성되지 않습니다). 예를 들어, 사용자 정의 버텍스 셰이더가 버텍스나 노멀을 변위시키는 경우, 이후 정확한 조명 계산을 수행하기 위해 수정된 값을 VERTEX 또는 NORMAL 에 저장해야 합니다. 또한, 이 함수는 보간된 데이터를 프래그먼트 셰이더로 전달하기 위해 ` VARYING `로 정의된 변수에 값을 쓸 수 있습니다. 이 함수나 ` POSITION `의 재정의가 없는 경우, ` POSITION `는 ` VERTEX `와 ` MODELVIEWPROJECTION_MATRIX`를 기반으로 계산되며, 이는 ` PrincipledMaterial `가 수행하는 방식과 동일합니다.

  다음은 유니폼으로 노출된 QML 속성을 활용하고, 프래그먼트 셰이더로 데이터를 전달하는 예시입니다:

  VARYING vec3 vNormal;
  VARYING vec3 vViewVec;
  
  void MAIN()
  {
      VERTEX.x += sin(uTime * 4.0 + VERTEX.y) * uAmplitude;
      vNormal = normalize(NORMAL_MATRIX * NORMAL);
      vViewVec = CAMERA_POSITION - (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
      POSITION = MODELVIEWPROJECTION_MATRIX * vec4(VERTEX, 1.0);
  }

  참고: 위예제에서 POSITION 에 값을 할당하는 것은 선택 사항입니다. 이 경우의 사용법은 기본 동작과 동일하기 때문입니다.

셰이딩이 적용된 사용자 정의 머티리얼의 프래그먼트 셰이더 코드 조각

다음 함수들은 프래그먼트 셰이더 스니펫에서 구현할 수 있습니다:

• void MAIN() 이 함수가 존재할 경우, 특수 쓰기 가능 변수 BASE_COLOR, METALNESS, ROUGHNESS, SPECULAR_AMOUNT, NORMAL, CLEARCOAT_FRESNEL_POWER, CLEARCOAT_FRESNEL_SCALE, CLEARCOAT_FRESNEL_BIAS, CLEARCOAT_AMOUNT, CLEARCOAT_ROUGHNESS, CLEARCOAT_NORMAL, FRESNEL_BIAS, FRESNEL_SCALE, FRESNEL_POWER, IOR, TRANSMISSION_FACTOR, THICKNESS_FACTOR, ATTENUATION_COLOR, ATTENUATION_DISTANCE 및 OCCLUSION_AMOUNT.

  일반적인 사용 사례 중 하나는 베이스 컬러 맵(base color map), SCREEN_TEXTURE 또는 기타 소스를 샘플링하여 BASE_COLOR 의 값을 설정하는 것입니다. 이는 특히 사용자 정의 라이트 프로세서 함수가 구현되지 않은 경우 유용하고 편리할 수 있습니다. BASE_COLOR.a 를 기본값인 1.0 이외의 값으로 설정하면 프래그먼트의 최종 알파 값에 영향을 줄 수 있습니다. (이 경우 대개 sourceBlend 및 destinationBlend 에서 알파 블렌딩을 활성화해야 한다는 점에 유의하십시오.)

  또 다른 시나리오는 사용자 정의 SPECULAR_LIGHT 함수가 제공되지 않거나, SceneEnvironment 에 라이트 프로브가 설정되어 있는 경우입니다. 이 경우, MAIN 에서 메탈니스, 러프니스 및 스페큘러 기여도 계산에 영향을 미치는 기타 값들을 원하는 사용자 정의 값으로 설정할 수 있습니다.

  이 함수는 다음 특수 변수에 값을 기록할 수 있습니다. 이 변수들에 기록되는 값은 일반적으로 하드코딩되거나, 유니폼에 매핑된 QML 속성을 기반으로 계산됩니다. 그 의미는 PrincipledMaterial 와 동일합니다.

  • vec4 BASE_COLOR - 기본 색상 및 머티리얼 알파 값입니다. built-in materials' color property 와 대응됩니다. 라이트 프로세서 함수가 구현되지 않은 경우, MAIN 에서 사용자 정의 기본 색상을 설정하는 것이 편리할 수 있습니다. 이렇게 설정된 값은 기본 조명 계산에 반영되기 때문입니다. 기본값은 vec4(1.0) 이며, 이는 알파 값이 1.0인 흰색을 의미합니다. 알파 값은 프래그먼트의 최종 알파 값에 영향을 미칩니다. 최종 알파 값은 오브젝트(모델)의 불투명도에 기본 색상 알파 값을 곱한 값입니다. QML의 색상 속성에서 노출된 유니폼 값에 의존하지 않고 셰이더 코드에서 직접 값을 지정할 경우, 필요한 경우 sRGB에서 선형(linear)으로의 변환을 수행하는 것은 셰이더의 몫이라는 점에 유의하십시오. 예를 들어, vec3 color 및 float alpha 를 가정할 때, 다음과 같이 구현할 수 있습니다:

    float C1 = 0.305306011;
    vec3 C2 = vec3(0.682171111, 0.682171111, 0.682171111);
    vec3 C3 = vec3(0.012522878, 0.012522878, 0.012522878);
    BASE_COLOR = vec4(rgb * (rgb * (rgb * C1 + C2) + C3), alpha);

  • vec3 EMISSIVE_COLOR - 자체 발광의 색상입니다. 이는 built-in materials's emissiveFactor property 및 built-in materials's emissiveMap property 를 조합하여 생성되는 내장 머티리얼의 발광 색상에 해당합니다. 기본값은 vec3(0.0) 입니다. QML의 색상 속성에서 노출된 균일(uniform) 값에 의존하지 않고 셰이더 코드에서 직접 값을 지정할 경우, 필요한 경우 sRGB에서 선형(linear)으로의 변환을 수행하는 것은 셰이더의 몫임을 유의하십시오.
  • float IOR 머티리얼의 굴절률을 지정합니다. 일반적인 값이자 기본값은 1.5 이며, 이는 PrincipledMaterial 에서 사용하는 값과 동일합니다.
  • float TRANSMISSION_FACTOR 반투명도의 정도를 지정합니다. 일반적인 값이자 기본값인 1.0 은 0.0 에서 사용하는 값이며, 이는 PrincipledMaterial 에서도 동일하게 적용됩니다.
  • float THICKNESS_FACTOR 반투명 머티리얼의 두께를 지정합니다. 일반적인 값은 10.0 이며, 기본값은 0.0 입니다. 이는 PrincipledMaterial 에서 사용하는 값과 동일합니다.
  • vec3 ATTENUATION_COLOR 거리에 따른 반투명 머티리얼의 색상 변화를 지정합니다. 일반적인 값은 vec3(1.0, 0.0, 0.0) 이며, 기본값은 vec3(1.0) 입니다. 이는 PrincipledMaterial 에서 사용하는 값과 동일합니다.
  • float ATTENUATION_DISTANCE 반투명 머티리얼의 색상 변위에 대한 거리 감쇠를 지정합니다. 일반적인 값은 100.0 이며, 기본값은 0.0 입니다. 이는 PrincipledMaterial 에서 사용하는 값과 동일합니다.
  • float METALNESS 0.0~1.0 범위의 금속성(Metalness) 정도입니다. 기본값은 0입니다. 효과를 보려면 0이 아닌 값으로 설정해야 합니다.
  • float ROUGHNESS 0.0~1.0 범위의 거칠기 값입니다. 기본값은 0입니다.
  • float CLEARCOAT_FRESNEL_POWER 클리어코트 레이어의 프레넬 강도를 지정합니다. 일반적인 값이자 기본값은 5.0 이며, 이는 PrincipledMaterial 에서 사용하는 값과 동일합니다.
  • float CLEARCOAT_FRESNEL_SCALE 클리어코트 레이어의 프레넬 스케일을 지정합니다. 일반적인 값이자 기본값은 1.0 이며, 이는 PrincipledMaterial 에서 사용하는 값과 동일합니다.
  • float CLEARCOAT_FRESNEL_BIAS 클리어코트 레이어의 프레넬 바이어스를 지정합니다. 일반적인 값이자 기본값은 0.0 이며, 이는 PrincipledMaterial 에서 사용하는 값입니다.
  • float CLEARCOAT_AMOUNT 머티리얼 상단에 적용되는 클리어코트 레이어의 양을 지정합니다. 일반적인 값은 1.0 이며, 기본값은 0.0 입니다. 이는 PrincipledMaterial 에서 사용하는 값과 동일합니다.
  • float CLEARCOAT_ROUGHNESS: 클리어코트 레이어의 거칠기를 지정합니다. 일반적인 값은 완전히 흐릿한 클리어코트 레이어의 경우 1.0 이며, 기본값은 0.0 입니다. 이는 PrincipledMaterial 에서 사용하는 값과 동일합니다.
  • vec3 CLEARCOAT_NORMAL - 월드 좌표계에서 버텍스 셰이더를 통해 전달되는 클리어코트 레이어의 법선 벡터입니다. 이 속성의 초기값은 VAR_WORLD_NORMAL 과 동일하지만, 클리어코트 레이어의 법선 벡터에는 CLEARCOAT_NORMAL 의 값만 변경해도 영향을 미칩니다.
  • float FRESNEL_POWER 프레넬 강도를 지정합니다. 일반적인 값이자 기본값은 5.0 이며, 이는 PrincipledMaterial 에서 사용하는 값과 동일합니다.
  • float FRESNEL_SCALE 프레넬 스케일을 지정합니다. 일반적인 값이자 기본값은 1.0 이며, 이는 PrincipledMaterial 에서 사용하는 값입니다.
  • float FRESNEL_BIAS 프레넬 바이어스를 지정합니다. 일반적인 값이자 기본값은 0.0 이며, 이는 PrincipledMaterial 에서 사용하는 값입니다.
  • float SPECULAR_AMOUNT 0.0~1.0 범위의 스페큘러 양입니다. 기본값은 0.5 이며, 이는 PrincipledMaterial::specularAmount 과 일치합니다. 효과가 나타나려면 0이 아닌 값으로 설정해야 합니다.
  • float OCCLUSION_AMOUNT AO 계수를 지정합니다. 일반적인 값이자 기본값은 1.0 이며, 이는 PrincipledMaterial 에서 사용하는 값과 동일합니다.
  • vec3 NORMAL - 월드 좌표계에서 정점 셰이더를 통해 전달되는 법선 벡터입니다. 이 속성의 초기값은 VAR_WORLD_NORMAL 과 동일하지만, 조명에 영향을 미치려면 NORMAL 의 값만 변경해야 합니다.
  • vec3 TANGENT - 월드 좌표계에서 버텍스 셰이더를 통해 전달되는 접선 벡터입니다. 이 값은 양면성에 따라 조정될 수 있습니다.
  • vec3 BINORMAL - 월드 좌표계에서 버텍스 셰이더를 통해 전달된 탄젠트 벡터입니다. 이 값은 양면성에 따라 조정될 수 있습니다.
  • vec2 UV0 - 버텍스 셰이더에서 반환되는 첫 번째 텍스처 좌표 세트입니다. 이 속성은 프래그먼트 셰이더에서 읽기 전용입니다.
  • vec2 UV1 - 버텍스 셰이더에서 반환된 두 번째 텍스처 좌표 세트입니다. 이 속성은 프래그먼트 셰이더에서 읽기 전용입니다.

  참고: 쉐이딩되지 않은 머티리얼과달리 , 쉐이딩된 머티리얼의 프래그먼트 MAIN 는 FRAGCOLOR 에 직접적인 영향을 미치지 않습니다. 오히려, 최종 프래그먼트 색상을 결정하는 것은 라이트 프로세서 함수에 작성된 DIFFUSE 및 SPECULAR 값입니다. 라이트 프로세서 함수가 구현되지 않은 경우, PrincipledMaterial 와 마찬가지로 관련 기본 쉐이딩 계산이 수행되며, 이때 BASE_COLOR 및 위 목록의 기타 값들이 고려됩니다.

  간단한 금속성 사용자 정의 머티리얼 셰이더의 예는 다음과 같을 수 있습니다:

  void MAIN()
  {
      METALNESS = 1.0;
      ROUGHNESS = 0.5;
      FRESNEL_POWER = 5.0;
  }

  텍스처를 샘플링하여 기본 색상과 알파 값을 설정하는 또 다른 예시는 다음과 같습니다:

  VARYING vec2 texcoord;
  void MAIN()
  {
      BASE_COLOR = texture(uColorMap, texcoord);
  }

• • TO_LIGHT_DIR
DIFFUSE
• void AMBIENT_LIGHT() 이 함수가 존재할 경우, 각 프래그먼트마다 한 번씩 호출됩니다. 이 함수의 역할은 전체 앰비언트 기여도를 쓰기 가능한 특수 변수 DIFFUSE 에 더하는 것입니다. 물론 다른 값을 계산하거나, DIFFUSE 을 전혀 건드리지 않고(앰비언트 조명을 완전히 무시하기 위해) 처리할 수도 있습니다. 이 함수가 아예 존재하지 않을 경우, 앰비언트 조명 기여도는 PrincipledMaterial 에서 수행하는 것처럼 일반적인 방식으로 계산됩니다.

  이 함수는 다음 특수 변수에 값을 기록할 수 있습니다:

  • vec3 DIFFUSE: 프래그먼트별로 확산광 기여도를 누적합니다. 라이트 프로세서 함수는 일반적으로 이 변수에 (+=)를 더합니다. 값을 덮어쓰면 다른 광원의 기여도가 손실되기 때문입니다.

  이 함수는 위 표에 나열된 행렬(예: MODEL_MATRIX) 및 벡터(예: CAMERA_POSITION) 유니폼 외에도 다음 특수 변수를 읽을 수 있습니다:

  • vec3 TOTAL_AMBIENT_COLOR 장면 내의 총 앰비언트 기여도입니다.

  예시:

  void AMBIENT_LIGHT()
  {
      DIFFUSE += TOTAL_AMBIENT_COLOR;
  }

• void DIRECTIONAL_LIGHT() 이 함수가 정의되어 있으면, 장면 내의 활성 방향광 각각에 대해 각 프래그먼트마다 호출됩니다. 이 함수의 역할은 확산광 기여도를 쓰기 가능한 특수 변수 DIFFUSE 에 더하는 것입니다. 이 함수는 아무 작업도 수행하지 않도록 선택할 수도 있으며, 이 경우 방향광의 확산광 기여도는 무시됩니다. 이 함수가 아예 존재하지 않을 때는, PrincipledMaterial 에서와 같이 방향광의 확산광 기여도가 정상적으로 누적됩니다.

  이 함수는 다음 특수 변수에 값을 쓸 수 있습니다:

  • vec3 DIFFUSE 프래그먼트별로 확산광 기여도를 누적합니다. 라이트 프로세서 함수는 일반적으로 이 값에 (+=)을 더합니다. 값을 덮어쓰면 다른 라이트의 기여도가 손실되기 때문입니다.

  이 함수는 위 표에 나열된 행렬(예: MODEL_MATRIX) 및 벡터(예: CAMERA_POSITION) 유니폼 변수 외에도 다음 특수 변수를 읽을 수 있습니다:

  • vec3 LIGHT_COLOR 확산광 색상.
  • float SHADOW_CONTRIB 그림자 기여도. 그림자가 전혀 없거나 그림자를 받지 않는 경우 1.0입니다.
  • vec3 확산광 색상.
  • float 그림자 기여도. 그림자가 전혀 없거나 그림자를 받지 않는 경우 1.0입니다.
  • vec3
NORMAL
• • 월드 공간에서의 법선 벡터
  • . vec4 BASE_COLOR 기본 색상 및 머티리얼 알파
  • 값.
  • float
METALNESS
• • 메탈니스
  • (Metalness)
  • 값. float ROUGHNESS 러프니스(Roughness) 값.

  예시:

  void DIRECTIONAL_LIGHT()
  {
      DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
  }

• void POINT_LIGHT() 이 함수가 정의되어 있으면, 씬 내의 활성 포인트 라이트 각각에 대해 각 프래그먼트마다 호출됩니다. 이 함수의 역할은 쓰기 가능한 특수 변수 ` DIFFUSE`에 확산광 기여도를 더하는 것입니다. 함수는 아무 작업도 수행하지 않도록 선택할 수도 있으며, 이 경우 점광원의 확산광 기여도는 무시됩니다. 함수가 전혀 정의되지 않은 경우, 점광원의 확산광 기여도는 ` PrincipledMaterial `가 수행하는 방식과 마찬가지로 정상적으로 누적됩니다.

  이 함수는 다음 특수 변수에 값을 쓸 수 있습니다:

  • vec3 DIFFUSE 프래그먼트당 확산광 기여도를 누적합니다.

  이 함수는 위 표에 나열된 행렬(예: MODEL_MATRIX) 및 벡터(예: CAMERA_POSITION) 유니폼 외에도 다음 특수 변수를 읽을 수 있습니다:

  • vec3 LIGHT_COLOR 확산광 색상.
  • float LIGHT_ATTENUATION 광원 감쇠.
  • float SHADOW_CONTRIB 그림자 기여도. 그림자가 전혀 없거나 그림자를 받지 않는 경우 1.0입니다.
  • vec3 TO_LIGHT_DIR 광원을 향하는 벡터.
  • vec3 NORMAL 월드 공간에서의 법선 벡터.
  • vec4 BASE_COLOR 기본 색상과 머티리얼 알파 값.
  • float METALNESS 메탈니스(Metalness) 양.
  • float ROUGHNESS 러프니스(Roughness) 양.

  예시:

  void POINT_LIGHT()
  {
      DIFFUSE += LIGHT_COLOR * LIGHT_ATTENUATION * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
  }

• void SPOT_LIGHT() 이 함수가 존재할 경우, 씬 내의 활성 스포트라이트 각각에 대해 각 프래그먼트마다 호출됩니다. 이 함수의 역할은 확산 기여도를 쓰기 가능한 특수 변수 DIFFUSE 에 더하는 것입니다. 함수는 아무 작업도 수행하지 않도록 선택할 수도 있으며, 이 경우 스포트라이트의 확산 기여도는 무시됩니다. 이 함수가 아예 존재하지 않을 경우, 스포트라이트의 확산광 기여도는 PrincipledMaterial 에서 수행하는 것처럼 정상적으로 누적됩니다.

  이 함수는 다음 특수 변수에 값을 쓸 수 있습니다:

  • vec3 DIFFUSE 프래그먼트별로 확산광 기여도를 누적합니다.

  이 함수는 위 표에 나열된 행렬(예: MODEL_MATRIX) 및 벡터(예: CAMERA_POSITION) 유니폼 변수 외에도 다음 특수 변수를 읽을 수 있습니다:

  • vec3 LIGHT_COLOR 확산광 색상.
  • float LIGHT_ATTENUATION 광원 감쇠.
  • float SHADOW_CONTRIB 그림자 기여도. 그림자가 전혀 없거나 그림자를 받지 않는 경우 1.0입니다.
  • vec3 TO_LIGHT_DIR 광원을 향하는 벡터.
  • float SPOT_FACTOR 스포트라이트 계수.
  • vec3 NORMAL 월드 공간에서의 법선 벡터.
  • vec4 BASE_COLOR 기본 색상과 머티리얼 알파 값.
  • float METALNESS 메탈니스(Metalness) 값.
  • float ROUGHNESS 러프니스(Roughness) 값.

  예시:

  void SPOT_LIGHT()
  {
      DIFFUSE += LIGHT_COLOR * LIGHT_ATTENUATION * SPOT_FACTOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
  }

• void SPECULAR_LIGHT() 이 함수가 존재할 경우, 씬 내의 활성화된 각 광원에 대해 각 프래그먼트마다 호출됩니다. 이 함수의 역할은 쓰기 가능한 특수 변수 SPECULAR 에 스페큘러 기여도를 추가하는 것입니다. 이 함수는 아무 작업도 수행하지 않도록 선택할 수도 있으며, 이 경우 광원으로부터의 스페큘러 기여도는 무시됩니다. 이 함수가 아예 존재하지 않을 경우, 빛으로부터의 스페큘러 기여도는 ` PrincipledMaterial `가 수행하는 것처럼 정상적으로 누적됩니다.

  이 함수는 다음 특수 변수에 값을 쓸 수 있습니다:

  • vec3 SPECULAR 프래그먼트별로 스페큘러 빛 기여도를 누적합니다. 라이트 프로세서 함수는 일반적으로 이 변수에 값을 더합니다(+=). 값을 덮어쓰면 다른 라이트의 기여도가 손실되기 때문입니다.

  이 함수는 위 표에 나열된 행렬(예: MODEL_MATRIX) 및 벡터(예: CAMERA_POSITION) 유니폼 외에도 다음 특수 변수를 읽을 수 있습니다:

  • vec3 LIGHT_COLOR 스펙큘러 라이트 색상.
  • float LIGHT_ATTENUATION 광원 감쇠. 방향성 광원의 경우 값은 1.0입니다. 스포트 광원의 경우 이 값은 void SPOT_LIGHT() 의 LIGHT_ATTENUATION * SPOT_FACTOR 값과 동일합니다.
  • float SHADOW_CONTRIB 그림자 기여도. 그림자가 전혀 없거나 그림자를 받지 않는 경우 1.0입니다.
  • vec3 FRESNEL_CONTRIB 내장 프레넬 계산에 따른 프레넬 기여도.
  • vec3 TO_LIGHT_DIR 광원을 향하는 벡터.
  • vec3 NORMAL 월드 공간에서의 법선 벡터.
  • vec4 BASE_COLOR 기본 색상과 머티리얼 알파 값.
  • float METALNESS 메탈니스(Metalness) 양.
  • float ROUGHNESS 러프니스(Roughness) 양.
  • float SPECULAR_AMOUNT 스페큘러 강도. 이 값은 0.0에서 1.0 사이이며, 사용자 정의 MAIN 함수에서 설정된 값과 동일합니다. 이 값은 FRESNEL_CONTRIB 에서 제공하는 내장 프레넬 기여도를 사용하지 않을 때 프레넬 기여도를 계산하는 데 유용합니다.

  void SPECULAR_LIGHT()
  {
      vec3 H = normalize(VIEW_VECTOR + TO_LIGHT_DIR);
      float cosAlpha = max(0.0, dot(H, normalize(NORMAL)));
      float shine = pow(cosAlpha, exp2(15.0 * (1.0 - ROUGHNESS) + 1.0) * 0.25);
      SPECULAR += shine * LIGHT_COLOR * FRESNEL_CONTRIB * SHADOW_CONTRIB * LIGHT_ATTENUATION;
  }

• void POST_PROCESS() 이 함수가 정의되어 있으면, 프래그먼트 파이프라인의 마지막 단계에서 호출됩니다. 이 함수의 역할은 최종 확산, 반사 및 발광 항을 적용하여 COLOR_SUM 를 완성하는 것입니다. 쉐이딩이 적용되지 않은 머티리얼에 대한 FRAGCOLOR 와 달리, COLOR_SUM 는 프레임버퍼에 기록되기 전에 자동으로 톤 매핑됩니다. 디버깅을 위해 색상으로 처리되어서는 안 되는 값을 출력하는 것이 때때로 유용할 수 있습니다. 톤 매핑으로 인해 이 값이 왜곡되는 것을 방지하려면, tonemapMode 속성을 TonemapModeNone

  로

  설정하여 톤 매핑을 비활성화할 수 있습니다
  • .

  이 함수는 다음 특수 변수에 값을 쓸 수 있습니다:

  • vec4 COLOR_SUM 프래그먼트 셰이더의 출력값입니다. 기본값은 vec4(DIFFUSE.rgb + SPECULAR + EMISSIVE, DIFFUSE.a)입니다
  .

  이 함수는 다음 특수 변수들을 읽을 수 있습니다.

  • vec4 프래그먼트 파이프라인의 최종 확산 항입니다
  • .
  • vec3 SPECULAR 프래그먼트 파이프라인의 최종 반사 항입니다.
  • vec3 EMISSIVE 프래그먼트 파이프라인의 최종 발광 항입니다.
  • vec2 UV0 - 버텍스 셰이더에서 온 첫 번째 텍스처 좌표 세트입니다.
  • vec2 UV1 - 버텍스 셰이더에서 전달된 두 번째 텍스처 좌표 세트.

  void POST_PROCESS()
  {
      float center_x = textureSize(SCREEN_TEXTURE, 0).x * 0.5;
      if (gl_FragCoord.x > center_x)
          COLOR_SUM = DIFFUSE;
      else
          COLOR_SUM = vec4(EMISSIVE, DIFFUSE.a);
  }

• void IBL_PROBE() 이 함수가 정의되어 있으면 IBL(이미지 기반 조명) 처리를 위해 호출됩니다. 이 함수의 역할은 IBL의 디퓨즈 및 스페큘러 기여도를 쓰기 가능한 특수 변수 DIFFUSE 및 SPECULAR 에 더하는 것입니다.

  이 함수는 다음 특수 변수에 값을 쓸 수 있습니다:

  • vec3 DIFFUSE 프래그먼트별로 확산광 기여도를 누적합니다.
  • vec3 SPECULAR 프래그먼트별로 스페큘러광 기여도를 누적합니다.

  이 함수는 다음 특수 변수들을 읽을 수 있습니다.

  • vec4 BASE_COLOR 기본 색상과 머티리얼 알파 값입니다.
  • float AO_FACTOR 스크린 공간 오클루전 계수입니다.
  • float SPECULAR_AMOUNT 스페큘러 양입니다.
  • float ROUGHNESS 프래그먼트 파이프라인의 최종 발광 항입니다.
  • vec3 NORMAL 월드 공간에서의 법선 벡터입니다.
  • vec3 VIEW_VECTOR 카메라 방향을 가리킵니다.
  • mat3 IBL_ORIENTATION 라이트 프로브의 방향입니다. SceneEnvironment::probeOrientation 에서 가져옵니다.

  void IBL_PROBE()
  {
      vec3 smpDir = IBL_ORIENTATION * NORMAL;
      DIFFUSE += AO_FACTOR * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, smpDir, IBL_MAXMIPMAP).rgb;
  }

함수 간 사용자 정의 변수

MAIN 함수에서 다른 함수들로 추가 변수를 전달할 수 있습니다. 새로운 사용자 정의 변수를 정의할 때는 SHARED_VARS 키워드를 사용할 수 있습니다. 이러한 사용자 정의 변수는 SHARED.<변수명>을 사용하여 접근할 수 있습니다.

예를 들어, 음영 처리된 사용자 정의 머티리얼은 MAIN에서 공유된 값을 가져와 다른 함수에서 이를 사용할 수 있습니다.

SHARED_VARS {
    vec3 colorThreshold;
};
void MAIN()
{
    BASE_COLOR = texture(baseColorMap, UV0);
    SHARED.colorThreshold = texture(thresholdMap, UV0).rgb;
}
void DIRECTIONAL_LIGHT()
{
    if (DIFFUSE >= SHARED.colorThreshold) {
        DIFFUSE = SHARED.colorThreshold;
        return;
    }
    DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB;
}

SHARED_VARS {
    float sheenIntensity;
    float sheenRoughness;
    vec3 sheenColor;
    vec3 outSheenColor;
};
void MAIN()
{
    ...
    vec4 tex = texture(uSheenMap, UV0);
    SHARED.sheenColor = tex.rgb;
    SHARED.sheenIntensity = tex.a;
    SHARED.sheenRoughness = uSheenRoughness;
    SHARED.outSheenColor = vec3(0.0);
}
void SPECULAR_LIGHT()
{
    SHARED.outSheenColor += ...;
}
void POST_PROCESS()
{
    COLOR_SUM = DIFFUSE + SPECULAR + EMISSIVE + SHARED.outSheenColor;
}

추가 특수 키워드

사용자 정의 프래그먼트 셰이더 코드는 사용자 정의 버텍스 셰이더에서 전달된 유니폼(예: CAMERA_DIRECTION 또는 CAMERA_POSITION) 및 바리에이팅에 자유롭게 접근할 수 있습니다. 또한, 특수 키워드로 사용할 수 있는 여러 내장 바리에이팅이 있습니다. 이 중 일부는 버텍스 MAIN 가 자체적으로 계산하여 전달할 수 있다는 점에서 선택적이지만, 데이터 중복을 줄이기 위해 프래그먼트 셰이더도 대신 이러한 내장 변수를 사용할 수 있습니다. 이러한 내장 변수는 라이트 프로세서 함수와 프래그먼트 MAIN에서 사용할 수 있습니다.

• vec3 VAR_WORLD_NORMAL - NORMAL_MATRIX 에 의해 변환된 보간된 법선.
• vec3 VAR_WORLD_TANGENT - MODEL_MATRIX 에 의해 변환된 보간된 탄젠트.
• vec3 VAR_WORLD_BINORMAL - 에 의해 변환된 보간된 바이노멀. MODEL_MATRIX
• vec3 NORMAL - 보간된 법선( VAR_WORLD_NORMAL)이 있는 그대로인 것과는 달리, 이 값은 양면성에 따라 조정될 가능성이 있습니다. 컬링이 비활성화된 상태에서 렌더링할 경우, 필요에 따라 법선이 반전됩니다. 따라서 모든 컬링 모드에서 올바르게 동작하도록 하려면, 조명 및 기타 계산에 VAR_WORLD_NORMAL 대신 NORMAL 를 사용하는 것이 권장됩니다.
• vec3 TANGENT - NORMAL 와 마찬가지로, 이 값은 양면성을 고려하여 조정될 수 있습니다. 컬링이 비활성화된 상태에서 렌더링할 경우, 필요에 따라 탄젠트가 반전됩니다.
• vec3 BINORMAL - NORMAL 과 마찬가지로, 이 값은 양면성에 따라 조정될 수 있습니다. 컬링이 비활성화된 상태에서 렌더링할 경우, 필요에 따라 빈노멀이 반전됩니다.
• vec3 VAR_WORLD_POSITION - 보간된 월드 공간 버텍스 위치 ((MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz)
• vec4 VAR_COLOR - 메시에서 색상이 제공된 경우 보간된 정점 색상입니다. 그렇지 않은 경우 vec4(1.0) 입니다.
• vec3 VIEW_VECTOR - 카메라 방향을 가리킵니다. 이는 사실상 CAMERA_POSITION - VAR_WORLD_POSITION 벡터를 정규화한 것입니다.
• vec4 FRAGCOORD - 현재 프래그먼트의 창 상대 좌표를 포함합니다.
• float FRAMEBUFFER_Y_UP - 프레임버퍼(텍스처) 좌표계에서 Y축이 위를 향할 때( (0, 0) 가 왼쪽 하단 모서리인 경우) 이 값은 1 가 됩니다. Y축이 아래를 향할 때( (0, 0) 가 왼쪽 상단 모서리인 경우) 이 값은 -1 가 됩니다. 기본 그래픽 API의 이러한 차이는 대부분의 사용자 정의 머티리얼에는 영향을 미치지 않습니다. 한 가지 주목할 만한 예외는 FRAGCOORD 를 기반으로 하지 않는 텍스처 좌표를 사용하여 SCREEN_TEXTURE 를 샘플링하는 경우입니다. SCREEN_TEXTURE 의 방향은 본질적으로 기본 그래픽 API에 연동되어 있으므로, 메시의 텍스처 좌표를 사용할 때는 Y 좌표에 적절한 조정이 필요할 수 있습니다.

  예를 들어, Rectangle 또는 Cube 메시에 적합한 다음 프래그먼트 셰이더는 씬의 불투명 오브젝트를 모델 위에 표시합니다:

  VARYING vec2 texcoord;
  void MAIN()
  {
      vec2 screencoord = texcoord;
      if (FRAMEBUFFER_Y_UP < 0.0) // effectively: if not OpenGL
          screencoord.y = 1.0 - screencoord.y;
      BASE_COLOR = texture(SCREEN_TEXTURE, screencoord);
  }

  SCREEN_TEXTURE 및 DEPTH_TEXTURE 이외의 텍스처를 샘플링할 때, 또는 FRAGCOORD 를 사용하여 텍스처 좌표를 계산할 때(이는 화면 및 깊이 텍스처에 접근하는 일반적인 사용 사례입니다), 이러한 조정은 필요하지 않습니다.

• float NDC_Y_UP - 정규화된 장치 좌표계에서 Y축이 위쪽을 향할 때는 1 값을, Y축이 아래쪽을 향할 때는 -1 값을 반환합니다. Y축이 아래쪽을 향하는 경우는 Vulkan으로 렌더링할 때 해당됩니다. 대부분의 머티리얼은 이 점을 고려할 필요가 없지만, 특정 고급 사용 사례에서는 이를 기반으로 분기 처리를 하는 것이 유용할 수 있습니다.
• float NEAR_CLIP_VALUE - 이 속성의 값은 클리핑 평면 범위가 -1 에서 시작하여 1 까지일 때 -1 입니다. 이는 OpenGL을 사용하여 렌더링할 때 해당됩니다. 다른 렌더링 백엔드의 경우 이 속성의 값은 0 이며, 이는 클리핑 평면 범위가 0 에서 1 까지임을 의미합니다. 이 값은 다음을 포함하는 특정 기법에서 유용합니다. DEPTH_TEXTURE

  예를 들어, 다음 프래그먼트 셰이더는 뎁스 버퍼의 값을 기반으로 위치를 재구성하여 현재 렌더링 중인 위치와의 거리를 계산하는 기법을 보여줍니다. INVERSE_PROJECTION_MATRIX 와 함께 사용할 경우, 뎁스 값은 정규화된 장치 좌표계여야 하므로 뎁스 값의 범위가 이를 반영하도록 설정하는 것이 중요합니다. NEAR_CLIP_VALUE 가 -1 일 때, 깊이 값은 -1 과 1 사이의 범위로 스케일링됩니다.

  void MAIN() {
      vec2 screen_uv = FRAGCOORD.xy / vec2(textureSize(SCREEN_TEXTURE, 0));
      float depth = texture(DEPTH_TEXTURE, screen_uv).r;
  
      if (NEAR_CLIP_VALUE < 0.0) // effectively: if opengl
          depth = depth * 2.0 - 1.0;
  
      vec4 unproject = INVERSE_PROJECTION_MATRIX * vec4(screen_uv, depth, 1.0);
      depth = (unproject.xyz / unproject.w).z;
      float viewVectorZ = (VIEW_MATRIX * vec4(VAR_WORLD_POSITION, 1.0)).z;
      depth = viewVectorZ - depth;
  
      BASE_COLOR = vec4(depth, depth, depth, 1.0);
  }

• float IBL_EXPOSE - 라이트 프로브가 방출하는 빛의 양입니다. 이는 SceneEnvironment::probeExposure 에서 파생됩니다.

  DIFFUSE += AO_FACTOR * IBL_EXPOSE * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;

• float IBL_HORIZON - 환경의 하반부에서 반사되는 빛의 수평 커트오프 값입니다. 이 값은 Horizon Cut-Off 에서 파생되지만 [-1, 0) 범위로 재매핑됩니다.

  vec3 diffuse += AO_FACTOR * IBL_EXPOSE * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;
  if (IBL_HORIZON > -1.0) {
      float ctr = 0.5 + 0.5 * IBL_HORIZON;
      float vertWt = smoothstep(ctr * 0.25, ctr + 0.25, NORMAL.y);
      float wtScaled = mix(1.0, vertWt, IBL_HORIZON + 1.0);
      diffuse *= wtScaled;
  }

• float IBL_MAXMIPMAP - IBL_TEXTURE의 최대 밉맵 레벨입니다.

인스턴싱

인스턴스 렌더링을 수행할 때는 위의 키워드 중 일부가 적용되지 않습니다. 다음 키워드는 인스턴스 렌더링에서만 사용할 수 있습니다:

• INSTANCE_MODEL_MATRIX -> mat4: MODEL_MATRIX 을 대체하며, 인스턴싱 변환을 포함합니다.
• INSTANCE_MODELVIEWPROJECTION_MATRIX -> mat4: MODELVIEWPROJECTION_MATRIX 을 대체하며, 인스턴싱 변환을 포함합니다.
• INSTANCE_COLOR -> vec4: 인스턴스 색상. ` COLOR`와 결합하여 사용됩니다.
• INSTANCE_DATA -> vec4, 인스턴스 사용자 정의 데이터.
• INSTANCE_INDEX -> int, 인스턴스 번호이자 인스턴싱 테이블 내의 인덱스입니다.

스크린, 깊이 및 기타 텍스처

렌더링 파이프라인은 특수한 렌더 패스에서 가져온 콘텐츠를 통해 사용자 정의 머티리얼 셰이더에 여러 텍스처를 제공할 수 있습니다. 이는 셰이딩이 적용된 사용자 정의 머티리얼과 셰이딩이 적용되지 않은 사용자 정의 머티리얼 모두에 적용됩니다.

예를 들어, 셰이더가 씬 내 불투명 오브젝트의 깊이 버퍼 내용을 포함하는 깊이 텍스처에 접근해야 할 수 있습니다. 이는 ` DEPTH_TEXTURE`을 샘플링하여 구현됩니다. 이러한 텍스처는 실제로 필요한 경우가 아니면 일반적으로 생성되지 않습니다. 따라서 버텍스 또는 프래그먼트 셰이더에 다음 키워드가 포함되면, 해당 텍스처를 생성하기 위한 — 잠재적으로 비용이 많이 드는 — 패스를 활성화하는 토글 역할도 합니다. (물론, SceneEnvironment 의 앰비언트 오클루전(ambient occlusion) 매개변수와 같은 다른 설정이나, 깊이 텍스처를 사용하는 후처리 효과로 인해 일부가 이미 활성화되어 있을 수도 있습니다. 이 경우 해당 텍스처는 사용자 정의 머티리얼과 무관하게 생성되므로, 머티리얼에서 이러한 특수 텍스처를 샘플링하더라도 텍스처 액세스 자체를 제외하면 추가적인 비용은 발생하지 않습니다)

• SCREEN_TEXTURE - 존재할 경우, 투명 머티리얼이나 SCREEN_TEXTURE를 사용하는 머티리얼을 제외한 씬의 내용을 포함하는 렌더링 패스의 컬러 버퍼를 가진 텍스처(sampler2D 또는 sampler2DArray)가 이 이름으로 셰이더에 노출됩니다. 이 텍스처는 렌더링 대상인 프레임버퍼의 내용을 필요로 하는 기법에 사용할 수 있습니다. SCREEN_TEXTURE 텍스처는 View3D 와 동일한 클리어 모드를 사용합니다. 이 텍스처들의 크기는 픽셀 단위로 View3D 의 크기와 일치합니다. 예를 들어, 프래그먼트 셰이더에는 다음과 같은 코드가 포함될 수 있습니다.

  vec2 uv = FRAGCOORD.xy / vec2(textureSize(SCREEN_TEXTURE, 0));
  vec2 displace = vec2(0.1);
  vec4 c = texture(SCREEN_TEXTURE, uv + displace);

  SCREEN_TEXTURE 를 사용할 때는 장면을 적절하고 신중하게 설계해야 한다는 점에 유의하십시오. 이러한 머티리얼을 사용하는 오브젝트는 텍스처에 표시될 것으로 예상되는 다른 모든 오브젝트보다 위에 위치하도록 신중하게 배치해야 합니다. 어떤 형태로든 반투명성을 사용하는 오브젝트는 절대 ‘ SCREEN_TEXTURE ’의 일부가 될 수 없습니다. 종종 ‘ SCREEN_TEXTURE ’는 ‘ BASE_COLOR ’와 함께 ‘ MAIN ’에서 사용됩니다. 예를 들어, 다음 사용자 정의 프래그먼트 셰이더는 엠보스 효과를 적용하는 동시에, 불투명한 오브젝트가 닿지 않은 프래그먼트는 투명하게 유지합니다. 이는 해당 머티리얼을 가진 오브젝트가 전면에 배치되어 있고 블렌딩이 활성화되어 있음을 전제로 합니다.

  void MAIN()
  {
      vec2 size = vec2(textureSize(SCREEN_TEXTURE, 0));
      vec2 uv = FRAGCOORD.xy / size;
  
      // basic emboss effect
      vec2 d = vec2(1.0 / size.x, 1.0 / size.y);
      vec4 diff = texture(SCREEN_TEXTURE, uv + d) - texture(SCREEN_TEXTURE, uv - d);
      float c = (diff.x + diff.y + diff.z) + 0.5;
  
      float alpha = texture(SCREEN_TEXTURE, uv).a;
      BASE_COLOR = vec4(vec3(c), alpha);
  }

  멀티뷰 렌더링에서 ` SCREEN_TEXTURE `는` sampler2DArray`입니다. ` VIEW_INDEX `를 사용하여 사용할 레이어를 선택하십시오. 두 가지 유형의 렌더링을 모두 지원하려는 VR/AR 애플리케이션의 경우, 다음과 같은 방법이 호환성이 높습니다.

  #if QSHADER_VIEW_COUNT >= 2
      vec4 c = texture(SCREEN_TEXTURE, vec3(uv, VIEW_INDEX));
  #else
      vec4 c = texture(SCREEN_TEXTURE, uv);
  #endif

• SCREEN_MIP_TEXTURE - 대부분의 측면에서 ` SCREEN_TEXTURE `와 동일하지만, 이 텍스처에는 밉맵이 생성된다는 점이 다릅니다. 화면 크기에 따라, 그리고 장면이 렌더링될 때마다 밉맵을 생성해야 하기 때문에 성능 측면에서 비용이 많이 드는 기능일 수 있습니다. 따라서 사용자 정의 머티리얼에서 텍스처 밉 레벨에 의존하는 기법(예: 셰이더에서 textureLod 사용)이 구현되어 있지 않은 한, 항상 SCREEN_TEXTURE 를 사용하는 것이 좋습니다.
• DEPTH_TEXTURE - 이 매개변수가 존재할 경우, (비선형화된) 뎁스 버퍼 내용을 담은 텍스처(sampler2D 또는 sampler2DArray)가 이 이름으로 셰이더에 노출됩니다. 불투명한 오브젝트만 포함됩니다. 예를 들어, 프래그먼트 셰이더에는 다음과 같은 코드가 포함될 수 있습니다:

  ivec2 dtSize = textureSize(DEPTH_TEXTURE, 0);
  vec2 dtUV = (FRAGCOORD.xy) / vec2(dtSize);
  vec4 depthSample = texture(DEPTH_TEXTURE, dtUV);
  float zNear = CAMERA_PROPERTIES.x;
  float zFar = CAMERA_PROPERTIES.y;
  float zRange = zFar - zNear;
  float z_n = 2.0 * depthSample.r - 1.0;
  float d = 2.0 * zNear * zFar / (zFar + zNear - z_n * zRange);
  d /= zFar;

  멀티뷰 렌더링의 경우, DEPTH_TEXTURE 는 sampler2DArray 입니다. 사용할 레이어를 선택하려면 VIEW_INDEX 를 사용하십시오. 두 가지 렌더링 유형을 모두 지원하려는 VR/AR 애플리케이션의 경우, 이식 가능한 접근 방식은 다음과 같습니다.

  #if QSHADER_VIEW_COUNT >= 2
      vec4 depthSample = texture(DEPTH_TEXTURE, vec3(uv, VIEW_INDEX));
  #else
      vec4 depthSample = texture(DEPTH_TEXTURE, uv);
  #endif

• NORMAL_ROUGHNESS_TEXTURE - 이 텍스처가 존재할 경우, 월드 공간 법선과 머티리얼 거칠기 정보가 포함된 텍스처(sampler2D)가 이 이름으로 셰이더에 노출됩니다. 불투명 오브젝트만 포함됩니다. 거칠기 값은 알파 채널에 저장됩니다. 예를 들어, 프래그먼트 셰이더에는 다음과 같은 코드가 포함될 수 있습니다:

  vec3 N = normalize(texture(NORMAL_ROUGHNESS_TEXTURE, uv).rgb);

• AO_TEXTURE - 이 매개변수가 존재하고 SceneEnvironment 에서 스크린 스페이스 앰비언트 오클루전(SSAO)이 활성화된 경우(즉, AO 강도와 거리가 모두 0이 아닐 때), SSAO 텍스처(sampler2D 또는 sampler2DArray)가 이 이름으로 셰이더에 노출됩니다. 이 텍스처를 샘플링하는 것은 셰이딩되지 않은 머티리얼에서 유용할 수 있습니다. 셰이딩된 머티리얼에는 앰비언트 오클루전 지원 기능이 내장되어 있습니다. 즉, 앰비언트 오클루전 계수가 자동으로 고려된다는 의미입니다. 반면, 셰이딩되지 않은 머티리얼의 프래그먼트 셰이더에서는 다음과 같이 코딩하여 동일한 효과를 얻을 수 있습니다:

  ivec2 aoSize = textureSize(AO_TEXTURE, 0);
  vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
  float aoFactor = texture(AO_TEXTURE, aoUV).x;

  멀티뷰 렌더링에서 ` AO_TEXTURE `는` sampler2DArray`입니다. ` VIEW_INDEX `를 사용하여 사용할 레이어를 선택하십시오. 두 가지 유형의 렌더링을 모두 지원하려는 VR/AR 애플리케이션의 경우, 다음과 같은 방식이 보편적으로 사용됩니다:

  #if QSHADER_VIEW_COUNT >= 2
      ivec2 aoSize = textureSize(AO_TEXTURE, 0).xy;
      vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
      float aoFactor = texture(AO_TEXTURE, vec3(aoUV, VIEW_INDEX)).x;
  #else
      ivec2 aoSize = textureSize(AO_TEXTURE, 0);
      vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
      float aoFactor = texture(AO_TEXTURE, aoUV).x;
  #endif

• IBL_TEXTURE - 이 기능은 특별한 렌더링 패스를 활성화하지는 않지만, 머티리얼에 ` Material::lightProbe `이 설정되어 있거나 모델이 ` SceneEnvironment::lightProbe`의 적용 범위에 속할 때 사용할 수 있습니다.

  void IBL_PROBE()
  {
      DIFFUSE += AO_FACTOR * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;
  }

• MOTION_VECTOR_TEXTURE — 씬 내 각 오브젝트에 대한 모션 벡터를 계산하는 전용 렌더링 패스를 활성화합니다. 출력은 4채널 텍스처로, R 및 G 성분에는 모델의 스케일링된 모션 벡터가 포함되며, B 및 A 성분에는 스케일링되지 않은 모션 벡터가 저장됩니다.
• VIEW_INDEX - 커스텀 셰이더 코드에서 사용될 때, 이는 (보간되지 않은) uint 변수입니다. 멀티뷰 렌더링이 사용되지 않을 경우, 값은 항상 0입니다. 멀티뷰 렌더링이 사용될 경우, 값은 현재 뷰 인덱스(예: gl_ViewIndex)입니다. 멀티뷰 렌더링이 활성화된 상태에서 DEPTH_TEXTURE 및 이와 유사한 기능과 함께 사용할 때 특히 유용합니다.

SceneEnvironment::tonemapMode, 이미지 기반 조명 사용법 (Qt Quick 3D ), 사용자 정의 셰이더 예제( Qt Quick 3D ) , 사용자 정의 머티리얼 예제( ), 프로그래밍 가능한 머티리얼, 이펙트, 지오메트리 및 텍스처 데이터도참조하십시오 .

속성 문서

alwaysDirty : bool

이 속성은 머티리얼 상태가 항상 ‘dirty’ 상태임을 지정하며, 이는 머티리얼이 QtQuick3D 에 의해 사용될 때마다 새로 고쳐져야 함을 의미합니다.

destinationAlphaBlend : enumeration [since 6.7]

대상 알파 블렌드 계수를 지정합니다. 기본값은 CustomMaterial.NoBlend 입니다. 이 값은 ‘ sourceBlend ’ 및 ‘ destinationBlend ’가 기본값이 아닌 값으로 설정된 경우에만 실제로 사용됩니다.

이 속성은 Qt 6.7에서 도입되었습니다.

destinationBlend도 참조하십시오 .

destinationBlend : enumeration

대상 혼합 계수를 지정합니다. 기본값은 CustomMaterial.NoBlend 입니다.

sourceBlend항목도 참조하십시오 .

fragmentShader : url

사용자 정의 프래그먼트 셰이더 코드 스니펫이 포함된 파일을 지정합니다.

값은 URL이어야 하며, 로컬 파일이어야 하거나 qrc 스키마를 사용하여 Qt 리소스 시스템을 통해 임베드된 파일에 접근해야 합니다. 상대 파일 경로(스키마 없음)도 허용되며, 이 경우 파일은 컴포넌트( .qml 파일)를 기준으로 상대 경로로 처리됩니다.

vertexShader도 참조하십시오 .

lineWidth : real

이 속성은 지오메트리가 ‘선’ 또는 ‘선 스트립’ 프라이미티브 유형을 사용할 때 렌더링되는 선의 너비를 결정합니다. 기본값은 1.0입니다. 이 속성은 삼각형 메쉬와 같은 다른 유형의 지오메트리를 렌더링할 때는 적용되지 않습니다.

shadingMode : enumeration

재질의 유형을 지정합니다. 기본값은 ‘Shaded’입니다.

sourceAlphaBlend : enumeration [since 6.7]

소스 알파 블렌드 계수를 지정합니다. 기본값은 CustomMaterial.NoBlend 입니다. 이 값은 sourceBlend 및 destinationBlend 가 기본값이 아닌 값으로 설정된 경우에만 실제로 사용됩니다.

이 속성은 Qt 6.7에서 도입되었습니다.

sourceBlend도 참조하십시오 .

sourceBlend : enumeration

소스 혼합 계수를 지정합니다. 기본값은 CustomMaterial.NoBlend 입니다.

destinationBlend항목도 참조하십시오 .

vertexShader : url

사용자 정의 버텍스 셰이더 코드 스니펫이 포함된 파일을 지정합니다.

값은 URL이어야 하며, 로컬 파일이어야 하거나 qrc 스키마를 사용하여 Qt 리소스 시스템을 통해 임베드된 파일에 접근해야 합니다. 상대 파일 경로(스키마 없음)도 허용되며, 이 경우 파일은 컴포넌트( .qml 파일)를 기준으로 상대 경로로 간주됩니다.

fragmentShader도 참조하십시오 .