Back to Qt.io
Contact Us Blog Download Qt
このページでは

CustomMaterial QML Type

モデルのシェーディングに使用されるカスタムマテリアルを作成するための基本コンポーネント。詳細...

Import Statement: import QtQuick3D
Inherits:

Material

プロパティ

詳細な説明

カスタムマテリアルを使用すると、マテリアルに対してカスタムシェーダーコードを適用でき、グラフィックスシェーダーレベルでのプログラミングが可能になります。頂点シェーダー、フラグメントシェーダー、あるいはその両方を指定できます。vertexShader およびfragmentShader プロパティは、シェーダーのスニペットを含むファイルを参照するURLであり、ShaderEffect やImage.source と非常に似た動作をします。カスタムマテリアルでは、file およびqrc スキームのみがサポートされています。また、file スキームを省略することも可能で、これにより便利な方法で相対パスを指定できます。このようなパスは、コンポーネント（.qml ファイル）の場所を基準として解決されます。

カスタムマテリアルの入門ガイドについては、「プログラム可能なマテリアル、エフェクト、ジオメトリ、およびテクスチャデータ」のページを参照してください。

はじめに

同じシーンの以下の2つのバージョンを比較してみましょう。左側の円柱は、組み込みの非プログラム可能なマテリアルを使用しています。このようなマテリアルは、幅広いプロパティを通じて設定できますが、内部で生成されるシェーダーについてはそれ以上の制御はできません。 右側では、同じ円柱に、アプリケーション側で提供された頂点シェーダーおよびフラグメントシェーダーのスニペットを参照する 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 要素のプロパティであることに注目してください。これらは通常通り値を変更したりアニメーション化したりすることができ、開発者が特別な操作を行うことなく、その値は自動的にシェーダーに公開されます。

その結果、頂点がアニメーションする円柱が完成します：

カスタム頂点シェーダーを使用したベントシリンダー

2種類のカスタムマテリアル

カスタムマテリアルには主に2つのタイプがあります。これはshadingMode プロパティによって指定されます。unshaded カスタムマテリアルでは、フラグメントシェーダーはシーン内のライト、ライトプローブ、影を無視して、単一のvec4 色を出力します。shaded マテリアルでは、シェーダーは特定の関数を実装し、組み込み変数を使用して照明や影の影響を考慮する必要があります。

通常、デフォルトではシェーデッドマテリアルが選択されており、これはshadingMode プロパティのデフォルト値にも反映されています。これは、シーンからの光や影の影響を受けつつ、頂点やジオメトリからのその他の入力データを変換したり、SCREEN_TEXTURE やDEPTH_TEXTURE をサンプリングするなどして、BASE_COLOR やEMISSIVE_COLOR のような値を独自の方法で決定する必要があるマテリアルに適しています。 さらに、このようなマテリアルでは、指向性ライト、ポイントライト、およびその他のライトからの寄与を計算するために使用される方程式を上書きし、再実装することも可能です。標準マテリアルが持つライティングなどの機能を提供するために、アプリケーションが提供するシェーダーのスニペットは、内部でQt Quick の3Dエンジンによって大幅に修正されています。

アンシェーデッドマテリアルは、オブジェクトの外観が完全にカスタムシェーダーコードによって決定される場合に役立ちます。 このようなマテリアルのシェーダーには、エンジンによる追加処理が最小限に留まるため、最終的なフラグメントカラーを決定するのは完全にシェーダー次第となります。これにより自由度は高まりますが、ライトなどシーン内の他の要素との統合の可能性は制限されます。

注： Qtが実行時に使用するグラフィックスAPIにかかわらず、シェーダー コードは 常にVulkanスタイルのGLSLで提供されます。

注： マテリアルによって提供される頂点シェーダーおよびフラグメントシェーダーのコードは 、それ自体では完全なGLSLシェーダーではありません。むしろ、これらは一連の関数を提供するものであり、その後、エンジンによってさらなるシェーダーコードが追加されます。

シェーダーへのデータの公開

CustomMaterialの動的プロパティは、QMLおよびQt Quick の機能を使用して変更やアニメーション化が可能であり、その値は自動的にシェーダーに公開されます。これは実際にはShaderEffect と非常に似ています。以下のリストは、プロパティのマッピング方法を示しています：

  • bool、int、real → bool、int、float
  • QColor、color → vec4。また、QMLで指定された色値がsRGB色空間であると仮定して、色はリニア変換されます。"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プロパティでTexture かCubeMapTexture のどちらが使用されているかによって異なります。enabled プロパティをfalseに設定すると、シェーダーに対してダミーのテクスチャが公開されます。これにより、シェーダーは引き続き機能しますが、不透明な黒の画像コンテンツを持つテクスチャをサンプリングすることになります。 サンプラーのプロパティは、常にTextureInput オブジェクトを参照する必要があり、Texture を直接参照してはならない点に注意してください。Texture のプロパティに関しては、ソース、タイリング、フィルタリングに関連するプロパティのみがカスタムマテリアルで暗黙的に考慮されます。それ以外（UV変換など）は、カスタムシェーダーが適切と判断する方法で実装する必要があります。

注： シェーダーコードで参照されているユニフォームに対応するプロパティが存在しない場合 、実行時にマテリアルを処理する際にシェーダーのコンパイルエラーが発生します。 これにはいくつかの例外があり、たとえばサンプラーユニフォームは、対応する QML プロパティが存在しない場合にダミーのテクスチャがバインドされますが、原則として、すべてのユニフォームおよびサンプラーは、CustomMaterial オブジェクト内で対応するプロパティが宣言されている必要があります。

シェーディングなしのカスタムマテリアル

以下は、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 の頂点シェーダーおよびフラグメントシェーダーのコード断片は、次のような形になるでしょう。最終的なシェーダーコードをアセンブルする際、uniformや頂点入力の宣言は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：頂点シェーダーにおける 2 番目のテクスチャ座標セット。関連するモデルのメッシュが 2 番目のテクスチャ座標セットを提供していない場合、値は 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、頂点シェーダーでのみ設定可能。点のトポロジーを持つジオメトリをレンダリングする場合、カスタム頂点シェーダーはこの値を1.0または別の値に設定する必要があります（シェーディングあり・なしのいずれのカスタムマテリアルでも同様です）。1以外の値のサポートに関する詳細については、PrincipledMaterial::pointSize を参照してください。

シェーディング付きカスタムマテリアル

shaded マテリアルは、PrincipledMaterial によって生成されるはずのシェーダーコードをaugments します。シェーディングなしのマテリアルは、頂点シェーダーおよびフラグメントシェーダーのメイン関数に関するロジックのほぼすべてを独自に提供し、ライティング、シャドウ、グローバルイルミネーションなどの生成コードの追加を妨げますが、シェーディングありのマテリアルでは、CustomMaterialがPrincipledMaterial であるかのように、シェーダー生成が通常通り行われます。 頂点シェーダーおよびフラグメントシェーダーのコードスニペットには、特定の時点で呼び出されるオプションの関数が用意されており、これにより、ライティングの計算や最終的なフラグメントカラーの算出に使用される色やその他の値をカスタマイズすることが可能になります。

シェーディングされたカスタムマテリアル用のフラグメントシェーダーは、単にMAIN 関数を実装するだけでなく、複数の関数を実装することも可能です。MAIN を含むすべての関数は、シェーディングされたカスタムマテリアルにおいて実装が任意です。空のシェーダースニペット、あるいはvertexShader やfragmentShader プロパティを一切指定しない場合でも、完全に有効です。

シェーディングされたカスタムマテリアルの頂点シェーダースニペット

頂点シェーダーのスニペットには、以下の関数を実装できます：

  • void MAIN() この関数が定義されている場合、POSITION （頂点シェーダーからの vec4 出力）の値を設定するため、またオプションで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 への値の代入は任意です。このケースでの使用法はデフォルトの動作と全く同じであるためです。

注： 頂点ステージからフラグメントステージへ、補間を行わずにデータを渡すには 、VARYING 宣言において、型名の前にflat キーワードを追加してください。

シェーディングが適用されたカスタムマテリアル内のフラグメントシェーダーのスニペット

フラグメントシェーダーのスニペットでは、以下の関数を実装できます：

  • 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 。

    一般的な使用例として、ベースカラーマップ、SCREEN_TEXTURE 、あるいはその他のソースをサンプリングして、BASE_COLOR の値を設定することが挙げられます。これは、カスタムライトプロセッサ関数が実装されていない場合に特に有用で便利です。BASE_COLOR.a をデフォルトの1.0以外の値に設定することで、フラグメントの最終的なアルファ値に影響を与えることができます。（この場合、多くの場合、sourceBlend およびdestinationBlend でアルファブレンディングを有効にする必要があることに注意してください）

    もう一つのシナリオは、カスタムSPECULAR_LIGHT 関数が提供されていない場合、またはSceneEnvironment にライトプローブが設定されている場合です。スペキュラー寄与の計算に影響を与えるメタレネス、ラフネス、およびその他の値は、MAIN で希望するカスタム値に設定できます。

    この関数は、以下の特殊変数に値を書き込むことができます。これらの変数に書き込まれる値は、通常、ハードコーディングされるか、ユニフォームにマッピングされたQMLプロパティに基づいて計算されます。その動作はPrincipledMaterial と同一です。

    • vec4BASE_COLOR - ベースカラーおよびマテリアルのアルファ値。built-in materials' color property に対応します。ライトプロセッサ関数が実装されていない場合、MAIN でカスタムベースカラーを設定しておくと便利です。そうすることで、デフォルトのライティング計算においてその値が考慮されるようになるためです。 デフォルト値はvec4(1.0) であり、これはアルファ値1.0の白色を意味します。このアルファ値は、フラグメントの最終的なアルファ値に影響を与えます。最終的なアルファ値は、オブジェクト（モデル）の不透明度とベースカラーのアルファ値を乗算した値となります。 QMLのカラープロパティから公開されているuniform値に依存せず、シェーダーコード内で直接値を指定する場合、必要に応じてsRGBからリニアへの変換をシェーダー側で行う必要がある点に注意してください。例えば、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);
    • vec3EMISSIVE_COLOR - 自己発光の色。 これは、built-in materials's emissiveFactor property およびbuilt-in materials's emissiveMap property によって合成される、組み込みマテリアルの発光色に対応します。デフォルト値はvec3(0.0) です。QMLのカラープロパティから公開されるuniform値に依存せず、シェーダーコード内で値を直接指定する場合、必要に応じてsRGBからリニアへの変換をシェーダー側で行う必要がある点に注意してください。
    • floatIOR マテリアルの屈折率を指定します。一般的な値であり、デフォルト値でもあるのは1.5 です。これは、PrincipledMaterial が使用する値と同じです。
    • floatTRANSMISSION_FACTOR 半透明の度合いを指定します。一般的な値は1.0 であり、デフォルト値もこれと同じです。これは、0.0 が使用する値であるためです。また、PrincipledMaterial でもこの値が使用されます。
    • floatTHICKNESS_FACTOR 半透明マテリアルの厚さを指定します。一般的な値は10.0 であり、デフォルト値も0.0 です。これはPrincipledMaterial で使用される値と同じです。
    • vec3ATTENUATION_COLOR 距離に応じた半透明マテリアルの色シフトを指定します。一般的な値はvec3(1.0, 0.0, 0.0) であり、デフォルト値もvec3(1.0) です。これは、PrincipledMaterial が使用する値と同じです。
    • floatATTENUATION_DISTANCE 半透明マテリアルの色シフトの距離減衰を指定します。一般的な値は100.0 であり、デフォルト値も0.0 です。これはPrincipledMaterial で使用される値と同じです。
    • floatMETALNESS 0.0～1.0の範囲のメタルネス量。デフォルト値は0です。効果を発揮させるには、0以外の値に設定する必要があります。
    • floatROUGHNESS 0.0～1.0の範囲のラフネス値。デフォルト値は0です。
    • floatCLEARCOAT_FRESNEL_POWER クリアコート層のフレネル指数を指定します。一般的な値であり、デフォルト値も5.0 です。これは、PrincipledMaterial が使用する値と同じです。
    • floatCLEARCOAT_FRESNEL_SCALE クリアコート層のフレネルスケールを指定します。一般的な値（およびデフォルト値）は1.0 です。これは、PrincipledMaterial が使用する値と同じです。
    • floatCLEARCOAT_FRESNEL_BIAS クリアコート層のフレネルバイアスを指定します。典型的な値であり、デフォルト値でもある0.0 は、PrincipledMaterial が使用する値です。
    • floatCLEARCOAT_AMOUNT マテリアル上にあるクリアコート層の量を指定します。一般的な値は1.0 であり、デフォルト値も0.0 です。これは、PrincipledMaterial が使用する値と同じです。
    • floatCLEARCOAT_ROUGHNESS クリアコート層の粗さを指定します。一般的な値は、完全にぼかされたクリアコート層の場合、1.0 です。また、デフォルト値は0.0 であり、これはPrincipledMaterial で使用される値です。
    • vec3CLEARCOAT_NORMAL - ワールド座標系における、頂点シェーダーから得られるクリアコート層の法線です。このプロパティの初期値はVAR_WORLD_NORMAL と同じですが、クリアコート層の法線に影響を与えるのはCLEARCOAT_NORMAL の値を変更した場合のみです。
    • floatFRESNEL_POWER フレネル強度を指定します。一般的な値であり、デフォルト値でもあるのは5.0 です。これは、PrincipledMaterial が使用する値だからです。
    • floatFRESNEL_SCALE フレネルスケールを指定します。一般的な値であり、デフォルト値でもある1.0 は、PrincipledMaterial が使用する値です。
    • floatFRESNEL_BIAS フレネルバイアスを指定します。一般的な値（およびデフォルト値）は0.0 です。これは、PrincipledMaterial が使用する値と同じです。
    • floatSPECULAR_AMOUNT 0.0～1.0の範囲のスペキュラー量。デフォルト値は0.5 で、PrincipledMaterial::specularAmount と一致しています。効果を発揮させるには、0以外の値に設定する必要があります。
    • floatOCCLUSION_AMOUNT AO係数を指定します。一般的な値であり、デフォルト値でもあるのは1.0 です。これは、PrincipledMaterial が使用する値と同じであるためです。
    • vec3NORMAL - ワールド座標系における、頂点シェーダーから出力される法線ベクトル。このプロパティの初期値はVAR_WORLD_NORMAL と同じですが、照明に影響を与えるのはNORMAL の値を変更した場合のみです。
    • vec3TANGENT - ワールド座標系における、頂点シェーダーから出力される接線ベクトルです。この値は、両面性に応じて調整される場合があります。
    • vec3BINORMAL - ワールド座標系における、頂点シェーダーから出力される接線ベクトル。この値は、両面表示に対応するために調整される可能性があります。
    • vec2UV0 - 頂点シェーダーからの最初のテクスチャ座標セット。このプロパティは、フラグメントシェーダーでは読み取り専用です。
    • vec2UV1 - 頂点シェーダーから渡される 2 番目のテクスチャ座標セット。このプロパティは、フラグメントシェーダー内では読み取り専用です。

    注： シェーディングされていないマテリアルとは異なり 、シェーディングされたマテリアルのフラグメントMAIN は、FRAGCOLOR を直接制御しません。むしろ、最終的なフラグメントカラーを決定するのは、ライトプロセッサ関数に記述されたDIFFUSE およびSPECULAR の値です。ライトプロセッサ関数が実装されていない場合、PrincipledMaterial と同様に、上記のリストにあるBASE_COLOR やその他の値を考慮に入れて、関連するデフォルトのシェーディング計算が行われます。

    シンプルなメタリックなカスタムマテリアルシェーダーの例としては、次のようなものがあります：

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

    もう1つの例として、テクスチャをサンプリングしてベースカラーとアルファを設定する場合があります：

    VARYING vec2 texcoord;
void MAIN()
{
    BASE_COLOR = texture(uColorMap, texcoord);
}
    • LIGHT_COLOR
    • DIFFUSE
  • void AMBIENT_LIGHT() この関数が定義されている場合、フラグメントごとに1回呼び出されます。この関数の役割は、書き込み可能な特殊変数 `DIFFUSE` にアンビエント光の合計寄与量を加算することです。もちろん、別の値を計算したり、`DIFFUSE ` を一切変更しなかったり（アンビエント照明を完全に無視する場合）することも可能です。 この関数が全く存在しない場合、アンビエント光の寄与は、PrincipledMaterial が実行するのと同様に、通常通り計算されます。

    この関数は、以下の特殊変数に書き込みを行うことができます：

    • vec3DIFFUSE フラグメントごとに、拡散光の寄与を蓄積します。ライトプロセッサ関数は通常、この変数に（+= ）を加算します。これは、値を上書きすると他のライトからの寄与が失われてしまうためです。

    この関数は、上記の表にある行列（例：MODEL_MATRIX ）やベクトル（例：CAMERA_POSITION ）のユニフォームに加え、以下の特殊変数を読み取ることができます：

    • vec3TOTAL_AMBIENT_COLOR シーン内のアンビエント光の総寄与量。

    例：

    void AMBIENT_LIGHT()
{
    DIFFUSE += TOTAL_AMBIENT_COLOR;
}
  • void DIRECTIONAL_LIGHT() 存在する場合、この関数はシーン内のアクティブな指向性ライトごとに、フラグメントごとに呼び出されます。 この関数の役割は、拡散光の寄与を書き込み可能な特殊変数 `DIFFUSE` に加算することです。この関数は何もしないことを選択することも可能で、その場合は方向性ライトからの拡散光の寄与は無視されます。この関数が全く存在しない場合、方向性ライトからの拡散光の寄与は、`PrincipledMaterial ` が行うのと同様に、通常通り累積されます。

    この関数は、以下の特殊変数に書き込みを行うことができます:

    • vec3 `DIFFUSE `：フラグメントごとに拡散光の寄与を蓄積します。値を上書きすると他の光からの寄与が失われるため、ライトプロセッサ関数は通常、これに `(+=)` を加算します。

    この関数は、上記の表にある行列（例：MODEL_MATRIX ）やベクトル（例：CAMERA_POSITION ）のユニフォームに加え、以下の特殊変数を読み取ることができます：

    • vec3LIGHT_COLOR 拡散光の色。
    • floatSHADOW_CONTRIB 影の寄与度。影が全くない場合や影を受けていない場合は 1.0 となります。
    • vec3TO_LIGHT_DIR 光源を指すベクトル。
    • vec3NORMAL ワールド空間における法線ベクトル。
    • vec4BASE_COLOR ベースカラーとマテリアルのアルファ値。
    • floatMETALNESS メタルネスの量。
    • floatROUGHNESS ラフネスの量。

    例：

    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 が実行するのと同様に、通常通り累積されます。

    この関数は、以下の特殊変数に書き込みを行うことができます：

    • vec3DIFFUSE フラグメントごとに、拡散光の寄与を蓄積します。

    この関数は、上記の表にある行列（例：MODEL_MATRIX ）やベクトル（例：CAMERA_POSITION ）のユニフォームに加え、以下の特殊変数を読み取ることができます：

    • vec3LIGHT_COLOR 拡散光の色。
    • floatLIGHT_ATTENUATION 光の減衰量。
    • floatSHADOW_CONTRIB 影の寄与度。影が全くない場合、または影を受けない場合は 1.0。
    • vec3TO_LIGHT_DIR 光源を指すベクトル。
    • vec3NORMAL ワールド空間における法線ベクトル。
    • vec4BASE_COLOR ベースカラーとマテリアルのアルファ値。
    • floatMETALNESS メタルネスの量。
    • floatROUGHNESS ラフネスの量。

    例：

    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 が実行するのと同様に、通常通り蓄積されます。

    この関数は、以下の特殊変数に書き込みを行うことができます：

    • vec3DIFFUSE フラグメントごとに拡散光の寄与を蓄積します。

    この関数は、上記の表にある行列（例：MODEL_MATRIX ）やベクトル（例：CAMERA_POSITION ）のユニフォーム変数に加え、以下の特殊変数を読み取ることができます：

    • vec3 拡散光の色。
    • floatLIGHT_ATTENUATION 光の減衰量。
    • floatSHADOW_CONTRIB 影の寄与度。影が全くない場合や影を受けていない場合は 1.0 となります。
    • vec3TO_LIGHT_DIR 光源の方向を指すベクトル。
    • floatSPOT_FACTOR スポットライト係数。
    • vec3NORMAL ワールド空間における法線ベクトル。
    • vec4BASE_COLOR ベースカラーとマテリアルのアルファ値。
    • floatMETALNESS メタリック度の量。
    • floatROUGHNESS ラフネスの量。

    例：

    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 が実行するのと同様に、通常通り累積されます。

    この関数は、以下の特殊変数に書き込みを行うことができます：

    • vec3SPECULAR フラグメントごとに、ライトからのスペキュラー寄与を累積します。 ライトプロセッサ関数は通常、この変数に（+= ）を加算します。これは、値を上書きすると他のライトからの寄与が失われてしまうためです。

    この関数は、上記の表にある行列（例：MODEL_MATRIX ）やベクトル（例：CAMERA_POSITION ）のユニフォームに加え、以下の特殊変数を読み取ることができます：

    • vec3LIGHT_COLOR スペキュラーライトの色。
    • floatLIGHT_ATTENUATION ライトの減衰量。指向性ライトの場合、値は 1.0 です。スポットライトの場合、値はvoid SPOT_LIGHT() のLIGHT_ATTENUATION * SPOT_FACTOR と同じです。
    • floatSHADOW_CONTRIB 影の寄与度。影が全くない場合や影を受けていない場合は 1.0 です。
    • vec3FRESNEL_CONTRIB 組み込みのフレネル計算によるフレネル寄与。
    • vec3TO_LIGHT_DIR 光源の方向を指すベクトル。
    • vec3NORMAL ワールド空間における法線ベクトル。
    • vec4BASE_COLOR ベースカラーとマテリアルのアルファ値。
    • floatMETALNESS メタリック度の量。
    • floatROUGHNESS ラフネスの量。
    • floatSPECULAR_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

    に

    設定してトーンマッピングを無効にできます
    • 。

    この関数は、以下の特殊変数に書き込むことができます：

    • vec4COLOR_SUM フラグメントシェーダーからの出力。デフォルト値は vec4(DIFFUSE.rgb + SPECULAR + EMISSIVE, DIFFUSE.a) です。

    この関数は、以下の特殊変数を読み取ることができます

    • 。
    • vec4 フラグメントパイプラインの最終的な拡散成分。
    • vec3SPECULAR フラグメントパイプラインの最終的な鏡面反射成分。
    • vec3EMISSIVE フラグメントパイプラインの最終的な発光成分。
    • vec2UV0 - 頂点シェーダーからの最初のテクスチャ座標セット。
    • vec2UV1 - 頂点シェーダーからの2番目のテクスチャ座標セット。
    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（Image-Based Lighting）のために呼び出されます。この関数の役割は、IBLの拡散光成分と鏡面反射光成分の両方を、書き込み可能な特殊変数DIFFUSE およびSPECULAR に加算することです。

    この関数は、以下の特殊変数に書き込みを行うことができます：

    • vec3DIFFUSE フラグメントごとに、拡散光の寄与を累積します。
    • vec3SPECULAR フラグメントごとに、スペキュラー光の寄与を累積します。

    この関数は、以下の特殊変数を読み取ることができます

      。
    • vec4BASE_COLOR ベースカラーおよびマテリアルのアルファ値。
    • floatAO_FACTOR スクリーンスペースのオクルージョン係数。
    • floatSPECULAR_AMOUNT スペキュラーの量。
    • floatROUGHNESS フラグメントパイプラインの最終的な発光項。
    • vec3NORMAL ワールド空間における法線ベクトル。
    • vec3VIEW_VECTOR カメラの方向を指すベクトル。
    • mat3IBL_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は 、POST_PROCESSを指定しないすべての関数に記述できますが、MAIN関数に記述し、他の関数で読み込むのが安全です。

    注： LIGHT関数にSHAREDを指定する推奨されるユースケースは 、まずMAINでその値をリセットし、その後、各LIGHT関数でその値を累積させることです。

    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;
}

    注：MAINは 他の関数よりも先に呼び出され、POST_PROCESSは他のすべての関数が実行された後に呼び出されますが、LIGHTプロセッサについては、それ以外の順序が保証されるわけではありません。

    その他の特別なキーワード

    カスタムフラグメントシェーダーのコードは、カスタム頂点シェーダーから渡されたユニフォーム（例：CAMERA_DIRECTION やCAMERA_POSITION など）やヴァリエイングに自由にアクセスできます。さらに、特別なキーワードとして利用可能な組み込みのヴァリエイングも多数用意されています。 これらのうち一部は、頂点MAIN が独自に計算して渡すことも可能であるという意味でオプションですが、データの重複を減らすために、フラグメントシェーダーは代わりにこれらの組み込み変数を利用することもできます。これらの組み込み変数は、ライトプロセッサの関数およびフラグメントMAINで使用可能です。

    • vec3VAR_WORLD_NORMAL -NORMAL_MATRIX によって変換された補間された法線。
    • vec3VAR_WORLD_TANGENT -MODEL_MATRIX によって変換された補間法線。
    • vec3VAR_WORLD_BINORMAL - によって変換された補正法線。MODEL_MATRIX
    • vec3NORMAL - そのままの補間された法線であるVAR_WORLD_NORMAL とは異なり、この値は両面表示に対応するために調整される可能性があります。カリングを無効にしてレンダリングする場合、必要に応じて法線が反転されます。したがって、すべてのカリングモードで正しく動作させるためには、照明やその他の計算において、VAR_WORLD_NORMAL の代わりにNORMAL を使用することをお勧めします。
    • vec3TANGENT -NORMAL と同様に、この値は両面性に合わせて調整される可能性があります。カリングを無効にしてレンダリングする場合、必要に応じて接線は反転されます。
    • vec3BINORMAL -NORMAL と同様に、この値は両面性に応じて調整される可能性があります。カリングを無効にしてレンダリングする場合、必要に応じてバイノーマルが反転されます。
    • vec3VAR_WORLD_POSITION - 補間されたワールド空間の頂点位置 ((MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz)
    • vec4VAR_COLOR - メッシュに色が指定されている場合の、補間された頂点色。それ以外の場合はvec4(1.0) 。
    • vec3VIEW_VECTOR - カメラの方向を指します。これは実質的に、CAMERA_POSITION - VAR_WORLD_POSITION ベクトルを正規化したものです。
    • vec4FRAGCOORD - 現在のフラグメントのウィンドウ相対座標を含みます。
    • floatFRAMEBUFFER_Y_UP - フレームバッファ（テクスチャ）の座標系において Y 軸が上を向いている場合、この値は1 となります。つまり、(0, 0) が左下隅となります。Y 軸が下を向いている場合、この値は-1 となり、(0, 0) が左上隅となります。このような基盤となるグラフィックス 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 を使用してテクスチャ座標を計算する場合（これはスクリーンテクスチャや深度テクスチャにアクセスする際の典型的なユースケースです）、このような調整は必要ありません。

    • floatNDC_Y_UP - 正規化されたデバイス座標空間で Y 軸が上向きの場合、この値は1 となり、Y 軸が下向きの場合は-1 となります。Vulkan を使用してレンダリングを行う場合、Y 軸は下向きになります。ほとんどのマテリアルではこれを気にする必要はありませんが、これに基づいて分岐処理を行えることは、特定の高度なユースケースにおいて有用となる場合があります。
    • floatNEAR_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);
}
    • floatIBL_EXPOSE - ライトプローブから放出される光の量。SceneEnvironment::probeExposure から算出されます。
      DIFFUSE += AO_FACTOR * IBL_EXPOSE * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;
    • floatIBL_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;
}
    • floatIBL_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 のアンビエントオクルージョンパラメータや、深度テクスチャに依存するポストプロセッシングエフェクトなどの他の設定により、これらの処理の一部がすでに有効になっている可能性があります。その場合、当該テクスチャはカスタムマテリアルに関係なく生成されるため、マテリアル内でこれらの特殊なテクスチャをサンプリングしても、テクスチャへのアクセス自体以外の追加コストは発生しません）

    • 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 は、MAIN においてBASE_COLOR と組み合わせて使用されます。例えば、以下のカスタムフラグメントシェーダーは、不透明なオブジェクトに触れていないフラグメントを透明なままに保ちつつ、エンボス効果を適用します。これは、そのマテリアルを持つオブジェクトが最前面に配置され、ブレンディングが有効になっていることを前提としています。

      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 でスクリーンスペースアンビエントオクルージョン（AO）が有効になっている場合（つまり、AO強度と距離の両方がゼロ以外である場合）、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

    マテリアルの状態を常に「ダーティ」に設定します。これにより、QtQuick3D によってマテリアルが使用されるたびに、そのマテリアルを更新する必要があることを示します。

    destinationAlphaBlend : enumeration [since 6.7]

    宛先のアルファブレンド係数を指定します。デフォルト値はCustomMaterial.NoBlend です。この値が実際に使用されるのは、sourceBlend およびdestinationBlend がデフォルト値以外の値に設定されている場合のみです。

    定数説明
    CustomMaterial.NoBlend 
    CustomMaterial.Zero 
    CustomMaterial.One 
    CustomMaterial.SrcColor 
    CustomMaterial.OneMinusSrcColor 
    CustomMaterial.DstColor 
    CustomMaterial.OneMinusDstColor 
    CustomMaterial.SrcAlpha 
    CustomMaterial.OneMinusSrcAlpha 
    CustomMaterial.DstAlpha 
    CustomMaterial.OneMinusDstAlpha 
    CustomMaterial.ConstantColor 
    CustomMaterial.OneMinusConstantColor 
    CustomMaterial.ConstantAlpha 
    CustomMaterial.OneMinusConstantAlpha 
    CustomMaterial.SrcAlphaSaturate

    注：下位互換性を確保するため 、デフォルト値のままにしておくと、sourceBlend およびdestinationBlend がデフォルト値以外の値に設定されている場合、destinationBlend と同じ値が割り当てられます。

    このプロパティは Qt 6.7 で導入されました。

    destinationBlendも参照してください 。

    destinationBlend : enumeration

    宛先のブレンド係数を指定します。デフォルト値はCustomMaterial.NoBlend です。

    定数説明
    CustomMaterial.NoBlend 
    CustomMaterial.Zero 
    CustomMaterial.One 
    CustomMaterial.SrcColor 
    CustomMaterial.OneMinusSrcColor 
    CustomMaterial.DstColor 
    CustomMaterial.OneMinusDstColor 
    CustomMaterial.SrcAlpha 
    CustomMaterial.OneMinusSrcAlpha 
    CustomMaterial.DstAlpha 
    CustomMaterial.OneMinusDstAlpha 
    CustomMaterial.ConstantColor 
    CustomMaterial.OneMinusConstantColor 
    CustomMaterial.ConstantAlpha 
    CustomMaterial.OneMinusConstantAlpha 
    CustomMaterial.SrcAlphaSaturate

    注： ブレンドを有効にするには、sourceBlend と destinationBlendの両方を デフォルト値以外の値に設定する必要があります。

    「sourceBlend」も参照してください 。

    fragmentShader : url

    カスタムフラグメントシェーダーコードのスニペットを含むファイルを指定します。

    値は URL であり、ローカルファイルであるか、qrc スキームを使用して Qt リソースシステム経由で埋め込まれたファイルにアクセスする必要があります。相対ファイルパス（スキームなし）も受け入れられます。その場合、ファイルはコンポーネント（.qml ファイル）を基準とした相対パスとして扱われます。

    警告：シェーダーの スニペットは信頼できるコンテンツであるとみなされます。アプリケーション開発者は、アプリケーションの一部ではないユーザー提供のコンテンツの読み込みを許可する前に、その潜在的な影響を慎重に検討することをお勧めします。

    vertexShaderも参照してください 。

    lineWidth : real

    このプロパティは、ジオメトリが「線」または「ラインストリップ」のプリミティブタイプを使用している場合に、描画される線の幅を決定します。デフォルト値は 1.0 です。このプロパティは、三角メッシュなど、他のタイプのジオメトリを描画する場合には関係ありません。

    警告： 基盤となるグラフィックス API によっては、1 以外の線幅が 実行時にサポートされない場合があります。その場合、線幅を変更する要求は無視されます。たとえば、Direct3D、Metal、コアプロファイルコンテキストを使用した OpenGL では、太い線のサポートは期待できません。

    注： 線幅の値がグラフィックスパイプラインオブジェクトの一部であるのとは異なり 、点で構成されるジオメトリのポイントサイズは（サポートされている場合）、頂点シェーダーによって制御されるため、対応する QML プロパティは存在しません。

    shadingMode : enumeration

    マテリアルの種類を指定します。デフォルト値は「Shaded」です。

    定数値
    CustomMaterial.Unshaded
    CustomMaterial.Shaded

    sourceAlphaBlend : enumeration [since 6.7]

    ソースのアルファブレンド係数を指定します。デフォルト値はCustomMaterial.NoBlend です。この値が実際に使用されるのは、sourceBlend およびdestinationBlend がデフォルト値以外の値に設定されている場合のみです。

    定数説明
    CustomMaterial.NoBlend 
    CustomMaterial.Zero 
    CustomMaterial.One 
    CustomMaterial.SrcColor 
    CustomMaterial.OneMinusSrcColor 
    CustomMaterial.DstColor 
    CustomMaterial.OneMinusDstColor 
    CustomMaterial.SrcAlpha 
    CustomMaterial.OneMinusSrcAlpha 
    CustomMaterial.DstAlpha 
    CustomMaterial.OneMinusDstAlpha 
    CustomMaterial.ConstantColor 
    CustomMaterial.OneMinusConstantColor 
    CustomMaterial.ConstantAlpha 
    CustomMaterial.OneMinusConstantAlpha 
    CustomMaterial.SrcAlphaSaturate

    注：下位互換性を確保するため 、デフォルト値のままにしておくと、sourceBlend およびdestinationBlend がデフォルト値以外に設定されている場合、sourceBlend と同じ値が割り当てられます。

    このプロパティは Qt 6.7 で導入されました。

    sourceBlendも参照してください 。

    sourceBlend : enumeration

    ソースのブレンド係数を指定します。デフォルト値はCustomMaterial.NoBlend です。

    定数説明
    CustomMaterial.NoBlend 
    CustomMaterial.Zero 
    CustomMaterial.One 
    CustomMaterial.SrcColor 
    CustomMaterial.OneMinusSrcColor 
    CustomMaterial.DstColor 
    CustomMaterial.OneMinusDstColor 
    CustomMaterial.SrcAlpha 
    CustomMaterial.OneMinusSrcAlpha 
    CustomMaterial.DstAlpha 
    CustomMaterial.OneMinusDstAlpha 
    CustomMaterial.ConstantColor 
    CustomMaterial.OneMinusConstantColor 
    CustomMaterial.ConstantAlpha 
    CustomMaterial.OneMinusConstantAlpha 
    CustomMaterial.SrcAlphaSaturate

    注： ブレンドを有効にするには、sourceBlend およびdestinationBlend の両方を デフォルト値以外の値に設定する必要があります。

    「destinationBlend」も参照してください 。

    vertexShader : url

    カスタム頂点シェーダーコードのスニペットが格納されたファイルを指定します。

    値はURLであり、ローカルファイルであるか、qrcスキーマを使用してQtリソースシステム経由で埋め込まれたファイルにアクセスする必要があります。相対ファイルパス（スキーマなし）も受け入れられ、その場合はファイルはコンポーネント（.qml ファイル）を基準とした相対パスとして扱われます。

    警告：シェーダーの スニペットは、信頼できるコンテンツであるとみなされます。アプリケーション開発者は、アプリケーションの一部ではないユーザー提供のコンテンツの読み込みを許可する前に、その潜在的な影響を慎重に検討することをお勧めします。

    fragmentShaderも参照してください 。

    © 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.