PrincipledMaterial QML Type

「金属／粗さ」ワークフローを使用して、3Dアイテムのマテリアルを定義できます。詳細...

• 継承されたメンバーを含む、すべてのメンバーの一覧

プロパティ

• alphaCutoff : real
• alphaMode : enumeration
• attenuationColor : color
• attenuationDistance : real
• baseColor : color
• baseColorChannel : enumeration (since 6.8)
• baseColorMap : Texture
• baseColorSingleChannelEnabled : bool (since 6.8)
• blendMode : enumeration
• clearcoatAmount : real
• clearcoatChannel : enumeration
• clearcoatFresnelBias : real
• clearcoatFresnelPower : real
• clearcoatFresnelScale : real
• clearcoatFresnelScaleBiasEnabled : real
• clearcoatMap : Texture
• clearcoatNormalMap : Texture
• clearcoatNormalStrength : real
• clearcoatRoughnessAmount : real
• clearcoatRoughnessChannel : enumeration
• clearcoatRoughnessMap : Texture
• emissiveChannel : enumeration (since 6.8)
• emissiveFactor : vector3d
• emissiveMap : Texture
• emissiveSingleChannelEnabled : bool (since 6.8)
• fresnelBias : real
• fresnelPower : real
• fresnelScale : real
• fresnelScaleBiasEnabled : real
• heightAmount : real
• heightChannel : enumeration
• heightMap : Texture
• indexOfRefraction : real
• invertOpacityMapValue : real (since 6.8)
• lighting : enumeration
• lineWidth : real
• maxHeightMapSamples : int
• metalness : real
• metalnessChannel : enumeration
• metalnessMap : Texture
• minHeightMapSamples : int
• normalMap : Texture
• normalStrength : real
• occlusionAmount : real
• occlusionChannel : enumeration
• occlusionMap : Texture
• opacity : real
• opacityChannel : enumeration
• opacityMap : Texture
• pointSize : real
• roughness : real
• roughnessChannel : enumeration
• roughnessMap : Texture
• specularAmount : real
• specularChannel : enumeration (since 6.8)
• specularMap : Texture
• specularReflectionMap : Texture
• specularSingleChannelEnabled : bool (since 6.8)
• specularTint : real
• thicknessChannel : enumeration
• thicknessFactor : real
• thicknessMap : Texture
• transmissionChannel : enumeration
• transmissionFactor : real
• transmissionMap : Texture
• vertexColorAlphaMask : enumeration (since 6.8)
• vertexColorBlueMask : enumeration (since 6.8)
• vertexColorGreenMask : enumeration (since 6.8)
• vertexColorRedMask : enumeration (since 6.8)
• vertexColorsEnabled : bool (since 6.5)
• vertexColorsMaskEnabled : bool (since 6.8)

詳細な説明

シーン内でモデルをレンダリングするには、メッシュのシェーディング方法を定義するマテリアルが少なくとも1つ、モデルに適用されている必要があります。PrincipledMaterialは、最小限のパラメータで使いやすさを追求したPBRメタル/ラフネスマテリアルです。 パラメータ数が少ないことに加え、すべての入力値は0から1の間で厳密に正規化されており、適切なデフォルト値が設定されています。つまり、値を一切変更しなくても、このマテリアルを使用してモデルのシェーディングを行うことができます。PrincipledMaterialの各プロパティがモデルのシェーディングにどのように影響するかについての概要については、「Principled Material」のサンプルを参照してください。

メタル／ラフネス・ワークフロー

Principledマテリアルは、いわゆるメタルネス/ラフネスマテリアルです。つまり、このマテリアルの主な特性は、metallness 、roughness 、およびbase color プロパティによって制御されます。

メタルネス

現実世界のマテリアルは、主に金属と誘電体（非金属）の2つのカテゴリに分類されます。Principledマテリアルでは、マテリアルがどのカテゴリに属するかは、metalness の値によって決定されます。metalness の値を0に設定すると、そのマテリアルは誘電体となり、0より大きい値はすべて金属とみなされます。現実の金属のmetalness 値は1ですが、0から1までの値も存在し、通常は反射率が低い金属に使用されます。 例えば、素材に腐食などの効果をレンダリングする場合、出力特性を誘電体素材により近づけるために、素材の「metalness 」を低く設定する必要があります。「metalness 」の値は素材の反射率に影響を与えるため、「metalness」を使って光沢を調整したくなるかもしれませんが、まずどのような素材を表現したいのかを検討してください。 誘電体素材に磨き上げられたような外観を与えるために「metalness 」の値を増やしても、誘電体素材としては不正確な特性が導入されてしまうため、代わりに「roughness 」の値を調整するほうが適切かどうかを検討してください。

粗さ

マテリアルの「roughness 」は、オブジェクトの表面の状態を表します。「roughness 」の値が低いほど、オブジェクトの表面は滑らかになり、その結果、「roughness 」の値が高いマテリアルよりも反射率が高くなります。

ベースカラー

金属／ラフネスマテリアルにおけるbase color には、拡散色と鏡面反射色の両方のデータが含まれており、ベースカラーがどちらとして解釈されるかは、主にmetalness の値によって決まります。 たとえば、メタレネス値が 1 のマテリアルでは、ベースカラーの大部分がスペキュラーカラーとして解釈され、拡散色は黒みがかった色調になります。メタレネス値が 0 のマテリアルでは、その逆の現象が起こります。これはもちろん多少単純化されていますが、base color とmetalness の値がどのように相互作用するかの大まかなイメージをつかむのに役立ちます。 スペキュラー／グロスネス（Specular/Glossiness）のワークフローに詳しい方にとっては、ここで注目すべき明確な違いがあります。それは、2つのマテリアルの色データが直接互換性を持たないという点です。なぜなら、スペキュラー／グロスネスのワークフロー（material ）では、拡散色と鏡面反射色は別々の入力から得られるからです。

プロパティのドキュメント

alphaCutoff : real

alphaCutoff プロパティは、Mask alphaMode を使用する際のカットオフ値を指定するために使用できます。アルファ値がしきい値を下回るフラグメントは、完全に透明（すべての色チャンネルで0.0 ）としてレンダリングされます。アルファ値がカットオフ値以上の場合、色には一切影響がありません。

デフォルト値は 0.5 です。

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

alphaMode : enumeration

このプロパティは、baseColor のアルファカラー値と、base color map のアルファチャンネルがどのように使用されるかを指定します。

alphaCutoff およびblendModeも参照してください 。

attenuationColor : color

このプロパティは、白色光が減衰距離に達した際に吸収によって変化する色を定義します。デフォルト値はQt.White

attenuationDistance : real

このプロパティは、光が媒質内で粒子と相互作用するまでの平均移動距離として定義される、媒質の密度を表します。値はワールド空間で指定されます。デフォルト値は+infinity です。

baseColor : color

このプロパティは、マテリアルの基底色を設定します。指定されたマテリアルの種類（金属または誘電体）に応じて、拡散チャンネルと鏡面反射チャンネルが適切に設定されます。 たとえば、誘電体マテリアルでは、拡散色はベースカラーと同じになりますが、スペキュラー色はスペキュラー量に応じて明るい色になります。金属の場合、拡散チャンネルとスペキュラーチャンネルはベースカラーを基に混合され、拡散チャンネルは暗い色になり、スペキュラーチャンネルはベースカラーに近い色になります。

baseColorMap およびalphaModeも参照してください 。

baseColorChannel : enumeration [since 6.8]

このプロパティは、baseColorMap からbaseColor の値を読み取る際に使用されるテクスチャチャンネルを定義します。単一のテクスチャチャンネルを色として使用するには、baseColorSingleChannelEnabled を有効にする必要があります。デフォルト値はMaterial.R です。

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

baseColorMap : Texture

このプロパティは、マテリアルのベースカラーを設定するために使用されるテクスチャを定義します。

「 baseColor 」および「alphaMode 」も参照してください 。

baseColorSingleChannelEnabled : bool [since 6.8]

このプロパティを有効にすると、マテリアルはbaseColorMap のbaseColorChannel から取得した単一の値をRGB値として使用し、アルファ値として1.0を使用します。デフォルト値はfalseです。

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

blendMode : enumeration

このプロパティは、レンダリングされたモデルの色が、その背後の色とどのように混ざり合うかを決定します。

「 alphaMode 」および「Qt Quick 3D Architecture」も参照してください 。

clearcoatAmount : real

このプロパティは、クリアコート層の濃度を定義します。

デフォルト値は0.0

clearcoatChannel : enumeration

このプロパティは、clearcoatMap からクリアコートの量を読み取る際に使用されるテクスチャチャネルを定義します。デフォルト値はMaterial.R です。

clearcoatFresnelBias : real

このプロパティは、接線方向の角度で見られる反射を維持しつつ、正面からの反射（表面をまっすぐ見た場合）を強調します。マテリアルに変更を反映させるには、「clearcoatFresnelScaleBiasEnabled 」を有効にする必要があります。デフォルト値は「0.0 」です。

clearcoatFresnelPower : real

このプロパティは、接線方向の反射を維持しつつ、正面からの反射（表面をまっすぐ見た場合）を低減します。デフォルト値は5.0 です。

clearcoatFresnelScale : real

このプロパティは、接線方向の反射を維持しつつ、正面からの反射（表面を真直ぐ見た場合）のスケールを調整します。マテリアルに変更を反映させるには、「clearcoatFresnelScaleBiasEnabled 」を有効にする必要があります。デフォルト値は「1.0 」です。

clearcoatFresnelScaleBiasEnabled : real

この値を「true」に設定すると、マテリアルは「クリアコート・フレネル・スケール」および「クリアコート・フレネル・バイアス」を考慮するようになります。デフォルト値は「false 」です。

clearcoatMap : Texture

このプロパティは、クリアコート層の濃淡を決定するために使用されるテクスチャを定義します。clearcoatAmount の値には、このテクスチャから読み取られた値が乗算されます。

clearcoatNormalMap : Texture

このプロパティは、クリアコート層に適用される法線マッピングを決定するために使用されるテクスチャを定義します。

clearcoatNormalStrength : real

このプロパティは、clearcoatNormalMap のシミュレーションによる変位量を制御します。

clearcoatRoughnessAmount : real

このプロパティは、クリアコート層の粗さを定義します。デフォルト値は0.0

clearcoatRoughnessChannel : enumeration

このプロパティは、clearcoatRoughnessMap からクリアコートの粗さを読み取るために使用されるテクスチャチャンネルを定義します。デフォルト値はMaterial.G です。

clearcoatRoughnessMap : Texture

このプロパティは、クリアコート層の粗さを決定するために使用されるテクスチャを定義します。clearcoatRoughnessAmount の値には、このテクスチャから読み取られた値が乗算されます。

emissiveChannel : enumeration [since 6.8]

このプロパティは、emissiveMap から発光値を読み取るために使用されるテクスチャチャネルを定義します。単一のテクスチャチャネルを色として使用するには、emissiveSingleChannelEnabled を有効にする必要があります。デフォルト値はMaterial.R です。

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

emissiveFactor : vector3d

このプロパティは、このマテリアルの自己発光の色を決定します。発光マップが設定されている場合、x、y、zの各成分は、テクスチャのR、G、Bチャンネルに対する係数（乗数）としてそれぞれ使用されます。 デフォルト値は (0, 0, 0) で、これは発光効果が全くないことを意味します。

emissiveMap : Texture

このプロパティは、発光色の輝度を指定するために使用するRGBテクスチャを設定します。

emissiveSingleChannelEnabled : bool [since 6.8]

このプロパティを有効にすると、マテリアルはemissiveMap のemissiveChannel から取得した単一の値をRGB値として使用します。デフォルト値はfalseです。

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

fresnelBias : real

このプロパティは、接線方向の角度で見られる反射を維持しつつ、正面からの反射（表面をまっすぐ見た場合）を強調します。マテリアルに変更を反映させるには、「fresnelScaleBiasEnabled 」を有効にする必要があります。デフォルト値は「0.0 」です。

fresnelPower : real

このプロパティは、接線方向の反射を維持しつつ、正面からの反射（表面をまっすぐ見た場合の反射）を低減します。デフォルト値は5.0 です。

fresnelScale : real

このプロパティは、接線方向の反射を維持しつつ、正面からの反射（表面をまっすぐ見た場合）のスケールを調整します。マテリアルに変更を反映させるには、「fresnelScaleBiasEnabled 」を有効にする必要があります。デフォルト値は「1.0 」です。

fresnelScaleBiasEnabled : real

この値を「true」に設定すると、マテリアルはフレネルスケールとフレネルバイアスを考慮するようになります。デフォルト値はfalse です。

heightAmount : real

このプロパティには、heightMap テクスチャの値を調整するために使用される係数が格納されています。値は0.0から1.0の間で指定する必要があります。デフォルト値は0.0であり、これは高さマップが設定されていても、高さの変位が無効になることを意味します。

heightChannel : enumeration

このプロパティは、heightMap から高さ値を読み取る際に使用されるテクスチャチャネルを定義します。デフォルト値はMaterial.R です。

heightMap : Texture

このプロパティは、パララックスマッピングを使用してレンダリングされる際に、テクスチャがどの程度ずれるかを決定するために使用されるテクスチャを定義します。値は 0.0 から 1.0 までの線形値が指定され、0.0 はずれなし、1.0 は最大ずれを意味します。

indexOfRefraction : real

このプロパティは、素材の屈折率を定義します。1.5 のデフォルト値は、プラスチックやガラスなどの素材にとっては理想的な値ですが、水、アスファルト、サファイア、ダイヤモンドなどの他の素材については、よりリアルに見えるように値を調整する必要があります。リアルな素材の場合、indexOfRefractionは通常、1.0 から3.0

一般的な物質の屈折率の例をいくつか挙げると：

invertOpacityMapValue : real [since 6.8]

このプロパティは、opacityMap の不透明度値を反転させます。デフォルト値はfalse です。

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

lighting : enumeration

このプロパティは、このマテリアルを生成する際に使用する照明方法を定義します。

デフォルト値はPrincipledMaterial.FragmentLighting

「PrincipledMaterial.FragmentLighting 」を使用する場合、レンダリングされる各ピクセルに対して拡散光および鏡面反射光が計算されます。特定のエフェクト（フレネル効果や法線マップなど）では、正常に機能させるために「PrincipledMaterial.FragmentLighting 」が必要です。

「PrincipledMaterial.NoLighting 」を使用する場合、ライティングは計算されません。このモードは（予想通り）非常に高速であり、ライティングによるシェーディングを必要としないイメージマップを使用する場合に非常に効果的です。「baseColor 」の値、アルファ値、および頂点色を除く、その他のすべてのシェーディングプロパティは無視されます。

lineWidth : real

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

maxHeightMapSamples : int

このプロパティは、heightMap を使用してパララックスオクルージョンマッピングを実行する際に使用されるサンプルの最大数を定義します。maxHeightMapSamples の値は、表面と平行な方向から見たときに、heightMap のサンプルのうち使用される数です。デフォルト値は 32 です。

各フラグメントで使用される実際のサンプル数は、レンダリング対象の表面に対するカメラの角度に応じて、minHeightMapSamples とmaxHeightMapSamplesの間になります。

metalness : real

「metalness」プロパティは、材料の金属性を定義します。この値は正規化されており、0.0 は材料が誘電体（非金属）であることを、1.0 は材料が金属であることを意味します。

範囲は [0.0, 1.0] です。デフォルト値は 0 です。

metalnessChannel : enumeration

このプロパティは、metalnessMap からメタルネス値を読み取る際に使用されるテクスチャチャンネルを定義します。デフォルト値はMaterial.B です。

metalnessMap : Texture

このプロパティは、マテリアルの各部分のメタルネス量を設定するために使用するテクスチャを指定します。

minHeightMapSamples : int

このプロパティは、heightMap を使用してパララックスオクルージョンマッピングを実行する際に使用されるサンプルの最小数を定義します。minHeightMapSamples の値は、表面を正面から見た場合（カメラの視点がフラグメントに対して垂直な場合）に、heightMap から使用されるサンプルの数です。デフォルト値は 8 です。

各フラグメントに対して実際に使用されるサンプル数は、レンダリングされる表面に対するカメラの角度に応じて、`minHeightMapSamples` と `maxHeightMapSamples ` の間の値となります。

normalMap : Texture

このプロパティは、マテリアルの表面全体にわたる微細なジオメトリの変位をシミュレートするために使用されるRGB画像を定義します。RGBチャンネルは、XYZ方向の法線偏差を表します。

normalStrength : real

このプロパティは、normalMap のシミュレーションによる変位量を制御します。

occlusionAmount : real

このプロパティには、occlusionMap テクスチャの値を調整するために使用される係数が格納されています。値は0.0から1.0の間で指定する必要があります。デフォルト値は1.0です。

occlusionChannel : enumeration

このプロパティは、occlusionMap からオクルージョン値を読み取る際に使用されるテクスチャチャネルを定義します。デフォルト値はMaterial.R です。

occlusionMap : Texture

このプロパティは、マテリアルの各領域がどの程度の光を受けるかを決定するために使用されるテクスチャを定義します。値は 0.0 から 1.0 までの線形値が想定されており、0.0 は照明が全く当たらない状態、1.0 は照明の効果が変更されない状態を意味します。

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

opacity : real

このプロパティは、モデルとは別に、このマテリアルだけの不透明度を下げます。

opacityChannel : enumeration

このプロパティは、opacityMap から不透明度値を読み取る際に使用するテクスチャチャネルを定義します。デフォルト値はMaterial.A です。

opacityMap : Texture

このプロパティは、マテリアルの各部分ごとに不透明度を個別に制御するために使用されるテクスチャを定義します。

pointSize : real

このプロパティは、ジオメトリが「点」のプリミティブ型を使用している場合に、レンダリングされる点のサイズを決定します。デフォルト値は 1.0 です。このプロパティは、三角メッシュなど、他の種類のジオメトリをレンダリングする場合には関係ありません。

roughness : real

このプロパティは、光源から生成されるスペキュラーハイライトの大きさや、反射の鮮明さを全体的に制御します。値を大きくするとラフネスが増し、スペキュラーハイライトが柔らかくなり、反射がぼやけます。設定範囲は [0.0, 1.0] です。デフォルト値は 0 です。

roughnessChannel : enumeration

このプロパティは、roughnessMap からラフネス値を読み取る際に使用されるテクスチャチャンネルを定義します。デフォルト値はMaterial.G です。

roughnessMap : Texture

このプロパティは、マテリアルのスペキュラーの粗さを制御するためのテクスチャを定義します。

specularAmount : real

このプロパティは、鏡面反射（ハイライトや反射）の強さを制御します。

範囲は[0.0, 1.0]です。デフォルト値は1.0 です。

specularChannel : enumeration [since 6.8]

このプロパティは、specularMap からスペキュラーカラーの値を読み取るために使用されるテクスチャチャンネルを定義します。単一のテクスチャチャンネルをカラーとして使用するには、specularSingleChannelEnabled を有効にする必要があります。デフォルト値はMaterial.R です。

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

specularMap : Texture

このプロパティは、マテリアルの表面全体におけるスペキュラーの量と色を調整するためのRGBテクスチャを定義します。これらの値は、specularAmount （反射率）に乗算されます。

specularReflectionMap : Texture

このプロパティは、マテリアルのスペキュラーハイライトに使用されるテクスチャを設定します。

これは通常、環境マッピングを行うために使用されます。モデルが回転すると、マップが環境から反射しているかのように見えます。これを期待通りに機能させるには、テクスチャの「mappingMode 」を「Texture.Environment」に設定する必要があります。スペキュラー反射マップは、比較的低コストで高品質な外観を追加できる簡単な方法です。

「Texture::mappingMode」も参照してください 。

specularSingleChannelEnabled : bool [since 6.8]

このプロパティを有効にすると、マテリアルはspecularMap のspecularChannel から取得した単一の値をRGB値として使用します。デフォルト値はfalseです。

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

specularTint : real

このプロパティは、ベースカラーが鏡面反射にどの程度寄与するかを定義します。

thicknessChannel : enumeration

このプロパティは、transmissionMap から厚さの値を読み取るために使用されるテクスチャチャンネルを定義します。デフォルト値はMaterial.G です。

thicknessFactor : real

このプロパティは、表面の下にある体積の厚さを定義します。PrincipledMaterial の他の多くのプロパティとは異なり、thicknessFactorで定義される値は、モデルの座標空間における厚さとして0.0から+無限大までの値となります。値が0.0の場合、その材料は薄肉であることを意味します。デフォルト値は0.0

thicknessMap : Texture

このプロパティは、マテリアルのボリュームの厚さを定義するために使用されるテクスチャを指定します。thicknessFactor の値には、このテクスチャから読み込まれた値が乗算されます。

transmissionChannel : enumeration

このプロパティは、transmissionMap から透過率を読み取る際に使用されるテクスチャチャンネルを定義します。デフォルト値はMaterial.R です。

transmissionFactor : real

このプロパティは、材料の表面を通過する光の割合（パーセンテージ）を定義します。デフォルト値は0.0

transmissionMap : Texture

このプロパティは、表面を通過する光の割合を決定するために使用されるテクスチャを定義します。transmissionFactor の値には、このテクスチャから読み取られた値が乗算されます。

vertexColorAlphaMask : enumeration [since 6.8]

このプロパティは、指定されたマスクとして使用される頂点カラーのアルファチャンネルを定義します。値はフラグのビット単位の組み合わせです。デフォルト値はPrincipledMaterial.NoMask です。

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

vertexColorBlueMask : enumeration [since 6.8]

このプロパティは、指定されたマスクとして使用される頂点色の青チャンネルを定義します。値はフラグのビット単位の組み合わせです。デフォルト値はPrincipledMaterial.NoMask です。

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

vertexColorGreenMask : enumeration [since 6.8]

このプロパティは、指定されたマスクとして使用される頂点色の緑チャンネルを定義します。値はフラグのビット単位の組み合わせです。デフォルト値はPrincipledMaterial.NoMask です。

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

vertexColorRedMask : enumeration [since 6.8]

このプロパティは、指定されたマスクとして使用される頂点色の赤チャンネルを定義します。値はフラグのビット単位の組み合わせです。デフォルト値はPrincipledMaterial.NoMask です。

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

vertexColorsEnabled : bool [since 6.5]

このプロパティを有効にすると、マテリアルはメッシュの頂点色を使用します。これらは、マテリアルに対して指定されたその他の色と乗算されます。デフォルト値は true です。

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

vertexColorsMaskEnabled : bool [since 6.8]

このプロパティを有効にすると、マテリアルはメッシュの頂点色を、RoughnessAmount や SpecularAmount などのさまざまなプロパティのマスクとして使用します。デフォルト値は false です。

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