Back to Qt.io
Contact Us Blog Download Qt

Texture QML Type

3Dシーンで使用するテクスチャを定義します。詳細...

Import Statement: import QtQuick3D
Inherits:

Object3D

Inherited By:

CubeMapTexture

プロパティ

詳細説明

テクスチャとは、厳密にはピクセルの配列（1D、2D、3D）と、それに関連する設定（最小化、拡大フィルター、スケーリング、UV変換など）のことです。

Qt Quick 3DのTextureタイプは、2次元画像を表します。その用途は、通常、3次元のジオメトリの上にマッピングしたり、3次元のジオメトリに巻き付けたりして、3次元では効率的にモデリングできない追加のディテールをエミュレートすることです。また、反射などの照明効果をエミュレートするためにも使用できます。

Texture自体は常に2Dテクスチャを表しますが、Textureのサブクラスを使って他の種類のテクスチャも利用できます。たとえば、6 面のキューブマップテクスチャを作成するには、CubeMapTexture タイプを使用します。

ジオメトリがレンダリングされるとき、その表面の各位置は、メッシュの頂点に設定された UV 座標（テクスチャ座標）を変換および補間することによって、テクスチャの対応する位置に変換されます。アクティブなマテリアルのレンダリングに使用されるフラグメントシェーダプログラムは、通常、指定された座標でマテリアルのテクスチャをサンプリングし、サンプリングされたデータをライト計算に使用します。

注意： マテリアルは、3Dシーンで光との相互作用を与えるために複数のテクスチャを使用することができます。ジオメトリサーフェス上の各テクセルの色だけでなく、サーフェスの他の属性も表現できます。例えば、"法線マップ "は、サーフェス上の各テクセルのジオメトリ法線からの偏差を表すことができ、ひび割れや凹凸など、サーフェス上の微細なディテールとの光の相互作用をエミュレートします。複数のテクスチャマップを持つマテリアルのデモについては、プリンシプルマテリアルの例を参照してください。

テクスチャオブジェクトは、イメージデータを

  • source プロパティを使用することで、画像またはテクスチャファイルから画像データを取得できます、
  • Qt QuickItem （sourceItem プロパティを使用）、
  • または、textureData プロパティをTextureData アイテムのサブクラスに設定して、カスタムテクスチャの内容を定義します。

次の例では、"madewithqt.png "という画像をデフォルトの球体メッシュにマッピングし、UV座標をスケーリングして球体表面に画像をタイル状に配置しています。

Model {
    source: "#Sphere"
    materials: [ PrincipledMaterial {
            baseColorMap: Texture {
                source: "madewithqt.png"
                scaleU: 4.0
                scaleV: 4.0
            }
        }
    ]
}

結果は次のようになります：

元の画像球体にマッピング

Qt Quick 3D - Procedural Texture Exampleも参照して ください。

プロパティの説明

autoOrientation : bool [since 6.2]

このプロパティは、Vテクスチャ座標を反転するようなテクスチャ変換を、通常関連するテクスチャに自動的に適用するかどうかを決定します。

デフォルトでは、このプロパティはtrueに設定されています。

.ktx や .pkm ファイルからsource プロパティ経由で読み込まれた圧縮テクスチャや、sourceItem プロパティ経由で Qt Quick シーンをレンダリングして生成されたテクスチャなど、特定のタイプのテクスチャデータは、.png や .jpg などの画像ファイルから読み込まれたテクスチャと比較して、Y 軸の向きが異なることがよくあります。そのため、このようなテクスチャは、ソースが通常の画像ファイルに設定されたテクスチャと比較して、「上下逆さま」に表示されます。これを改善するために、flipV プロパティが true に設定されているかのように、修飾された Texture は暗黙の UV 変換を受けます。これを望まない場合は、このプロパティを false に設定してください。

注: このプロパティは、Texture が DefaultMaterial またはPrincipledMaterial と組み合わせて使用される場合に有効です。Custom materials は、独自のシェーダーコードを提供するため、このプロパティで設定されるような変換は無視され、アプリケーションが提供するシェーダーコードの実装次第となります。

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

flipVも参照してください 。


flipU : bool

このプロパティは、水平方向に反転したテクスチャ座標の使用を設定します。

デフォルトは false です。

注: このプロパティは、Texture が DefaultMaterial またはPrincipledMaterial と組み合わせて使用される場合に有効です。Custom materials は、独自のシェーダー・コードを提供するため、このプロパティで設定されるような変換は無視され、アプリケーション提供のシェーダー・コードが実装することになります。

flipVも参照してください 。


flipV : bool

このプロパティは、垂直方向に反転したテクスチャ座標の使用を設定します。

デフォルトは false です。

注: このプロパティは、Texture が DefaultMaterial またはPrincipledMaterial と組み合わせて使用される場合に有効です。Custom materials は独自のシェーダー コードを提供するため、このプロパティで設定されるような変換は無視され、実装するのはアプリケーションが提供するシェーダー コードに任されます。

flipUも参照してください 。


generateMipmaps : bool

このプロパティは、ミップマップレベル自体を提供しないテクスチャに対してミップマップを生成するかどうかを決定します。ミップフィルタリングと共にミップマップを使用すると、ミップマップを使用しないレンダリングと比較して、テクスチャを離れた位置で表示する際の視覚的品質が向上しますが、パフォーマンスコストがかかる場合があります（画像の初期化時とレンダリング時の両方）。

デフォルトでは、このプロパティは false に設定されています。

注意 : 生成されたミップマップを使用するには、mipFilter モードを設定する必要があります。

注意 : このプロパティは、テクスチャの内容がsourceItem プロパティによって参照される Qt Quick アイテムに基づいている場合には適用されません。ダイナミックテクスチャのミップマップ生成は、パフォーマンスへの影響から実行不可能です。したがって、そのようなテクスチャでは、このプロパティの値は無視されます。

mipFilterも参照してください 。


indexUV : int

このプロパティは、このテクスチャが使用する UV 座標インデックスを設定します。QtQuick3D は今のところ2つのUVセット（0または1）をサポートしているため、値はその範囲に飽和します。

デフォルトは 0 です。


magFilter : enumeration

このプロパティは、テクスチャが「拡大」されたとき、つまりテクセルがスクリーンスペースで1ピクセル以上をカバーするときに、テクスチャがどのようにサンプリングされるかを決定します。

デフォルト値はTexture.Linear です。

定数説明
Texture.Nearest最も近いテクセルの値を使用します。
Texture.Linearは、最も近い4つのテキセルを取り、それらをバイリニア補間します。

注意: ここでTexture.None を使用すると、デフォルトはTexture.Linear になります。

minFilter およびmipFilterも参照してください 。


mappingMode : enumeration

このプロパティは、このテクスチャをサンプリングするときに使用するマッピング方法を定義します。

定数説明
Texture.UVデフォルト値です。ベースカラー、ディフューズ、不透明度、その他ほとんどのテクスチャマップに適しています。標準的な UV マッピングを行います。UV 座標が変換され、アニメーションされない限り、イメージの同じ部分は常に同じ頂点に表示されます。
Texture.Environmentspecular reflection に使用すると、画像が反射しているかのようにマテリアルに投影されます。他のタイプのテクスチャマップにこのモードを使用すると、ミラー効果が得られます。
Texture.LightProbeライトプローブで使用されるHDRI球体マップのデフォルトです。このモードは、lightProbe プロパティに関連付けられているテクスチャオブジェクトに対して手動で設定する必要はありません。

minFilter : enumeration

このプロパティは、テクスチャが "最小化 "されているとき、つまり、テクセルがスクリーンスペースで1ピクセル未満しかカバーしていないときに、テクスチャがどのようにサンプリングされるかを決定します。

デフォルト値はTexture.Linear です。

定数説明
Texture.Nearest最も近いテクセルの値を使用します。
Texture.Linearは、最も近い4つのテキセルを取り、それらをバイリニア補間します。

注意: ここでTexture.None を使用すると、デフォルトはTexture.Linear になります。

magFilter およびmipFilterも参照してください 。


mipFilter : enumeration

このプロパティは、テクセルが 1 ピクセル未満しかカバーしていない場合に、テクスチャのミッ プマップをどのようにサンプリングするかを決定します。

デフォルト値はTexture.None です。

定数説明
Texture.Noneミップマップサンプリングの使用を無効にします。
Texture.Nearestミップマップを使用し、最も近いテクセル値をサンプリングします。
Texture.Linearはミップマッピングを使用し、複数のテクセル値の間を補間します。

注意： このプロパティは、ミップマップを持たない Texture には影響しません。

minFilter およびmagFilterも参照してください 。


pivotU : float

このプロパティは、rotationUV を適用するときに使用されるピボット U 位置を設定します。

デフォルトは 0.0 です。

注: このプロパティは、Texture が DefaultMaterial またはPrincipledMaterial と組み合わせて使用される場合に有効です。Custom materials は独自のシェーダー コードを提供するため、このプロパティで設定されるような変換は無視され、実装するのはアプリケーションが提供するシェーダー コードに任されます。

rotationUVも参照してください 。


pivotV : float

このプロパティは、rotationUV を適用するときに使用されるピボット V 位置を設定します。

デフォルトは 0.0 です。

注: このプロパティは、Texture が DefaultMaterial またはPrincipledMaterial と組み合わせて使用される場合に有効です。Custom materials は独自のシェーダー コードを提供するため、このプロパティで設定されるような変換は無視され、実装するのはアプリケーション提供のシェーダー コードに任されます。

pivotU およびrotationUVも参照してください 。


positionU : float

このプロパティは U 座標マッピングを左から右にオフセットします。

デフォルトは 0.0 です。

注: このプロパティは、Texture が DefaultMaterial またはPrincipledMaterial と組み合わせて使用される場合に有効です。Custom materials は独自のシェーダー コードを提供するため、このプロパティで設定されるような変換は無視され、実装するのはアプリケーションが提供するシェーダー コードに任されます。

positionVも参照してください 。


positionV : float

このプロパティは V 座標マッピングを下から上にオフセットします。

デフォルトは 0.0 です。

注意: Qt Quick 3D は、実行時に使用されるグラフィックス API に関係なく、OpenGL スタイルの頂点データを使用します。そのため、UV位置(0, 0) は画像データの左下隅を参照しています。

注: このプロパティは、Texture が DefaultMaterial またはPrincipledMaterial と組み合わせて使用される場合に有効です。Custom materials は、独自のシェーダーコードを提供するため、このプロパティで設定されるような変換は無視され、アプリケーションが提供するシェーダーコードの実装次第となります。

positionUも参照してください 。


rotationUV : float

このプロパティは、ピボットポイントを中心にテクスチャを回転させます。これはオイラー角を使用して定義され、正の値の回転は時計回りです。

デフォルトは 0.0 です。

注意： このプロパティは、テクスチャが DefaultMaterial またはPrincipledMaterial と組み合わせて使用される場合に有効です。Custom materials は独自のシェーダコードを提供するため、このプロパティで設定されるような変換は無視され、実装するのはアプリケーションが提供するシェーダコードに任されます。

pivotU およびpivotVも参照してください 。


scaleU : float

このプロパティは、メッシュの UV 座標にマッピングするときに U テクスチャ座標をスケーリングする方法を定義します。

水平タイリングを使用するときに U 値をスケーリングすると、テクスチャが左から右に何回繰り返されるかが定義されます。

デフォルトは1.0です。

注意: このプロパティは、Texture が DefaultMaterial またはPrincipledMaterial と組み合わせて使用される場合に有効です。Custom materials は独自のシェーダーコードを提供するため、このプロパティで設定されるような変換は無視され、アプリケーションが提供するシェーダーコードの実装次第となります。

tilingModeHorizontalも参照してください 。


scaleV : float

このプロパティは、メッシュの UV 座標にマッピングするときに V テクスチャ座標をスケーリングする方法を定義します。

垂直タイリングを使用するときに V 値をスケーリングすると、テクスチャが下から上へ何回繰り返されるかが定義されます。

デフォルトは1.0です。

注意: このプロパティは、Texture が DefaultMaterial またはPrincipledMaterial と組み合わせて使用される場合に有効です。Custom materials は独自のシェーダーコードを提供するため、このプロパティで設定されるような変換は無視され、アプリケーションが提供するシェーダーコードの実装次第となります。

tilingModeVerticalも参照してください 。


source : url

このプロパティは、テクスチャによって使用されるデータを含むイメージまたはテクスチャファイルの場所を保持します。

このプロパティは URL であり、Image.source などの他のソース・プロパティと同じ規則が適用されます。Texture では、qrc とfile スキームのみがサポートされています。スキームが存在せず、値が相対パスの場合、コンポーネント（つまり.qml ファイル）の場所からの相対パスと見なされます。

ソ ース フ ァ イ ルは、 従来の画像フ ァ イ ル形式supported by Qt であれば何でもかまいません。さらに、Texture は QtQuick::Image と同じcompressed texture file types をサポートしています。

注意: .png や .jpg のようなイメージファイルから読み込まれたテクスチャデータは、Qt Quick 3D レンダリングエンジンで定義された順序でテクスチャ内のピクセル行を格納します。ソースファイルが圧縮されたテクスチャデータのコンテナである場合、このような変換はピクセルデータレベルではできません。この例としては、.ktx や .pkm ファイルがあります。その代わり、Texture は、画面上で同一の結果を得るために、フラグメントシェーダコードで垂直反転を暗黙的に有効にします。これはautoOrientation プロパティで制御され、必要に応じて無効にできます。

注意： テクスチャ圧縮ツールの中には、画像データに自動垂直ミラーリング（反転）を適用するものがあります。最近のツールでは、これはしばしばオプトイン設定です。アセットコンディショニングパイプラインで使用される設定に注意することが重要です。予期せずテクスチャが反転し、オブジェクトのテクスチャリングが不正確になることがありますが、その根本的な原因はアセット自体にあり、アプリケーションやレンダリングエンジンの制御外である可能性があるからです。アセットがそれを必要とする場合、アプリケーションは常に自分でflipV プロパティを設定できます。

sourceItem 、textureData 、autoOrientation 、flipVも参照して ください。


sourceItem : Item

このプロパティは、テクスチャのソースとして使用するアイテムを定義します。このプロパティを使用すると、そのアイテムをオフスクリーンレイヤーとしてレンダリングすることで、任意の 2D Qt Quick コンテンツをテクスチャソースとして使用できます。

アイテムがtexture provider の場合、追加のテクスチャは使用されません。

このプロパティが設定されている場合、source の値は無視されます。テクスチャは、1 つのメソッドを使用して画像データを提供し、source、sourceItem、textureData のうち 1 つだけを設定する必要があります。

注意： 現在のところ、入力イベントは、ユーザーが一度に1つの sourceItem インスタンスと対話するように制限されている場合にのみ、テクスチャソースとして使用される Item に転送されます。言い換えると、複数のTexture間で同じItemを共有することはできますが、その場合、同時に複数のTexture上で同じアイテムとのマルチタッチインタラクションを行うことはできません。そのため、内部でインタラクティブなアイテムを操作する場合は、Textureインスタンスごとに別々の2Dサブシーンインスタンスを使用するのがベストです。

注意: 複数のウィンドウから参照される Texture でこのプロパティを使用することは強く推奨されません。これにはView3D::importScene 経由での使用も含まれます。このプロパティによって作成されたソーステクスチャは、1つのレンダリングスレッドからのみアクセス可能であるため、デフォルトのthreaded の代わりに Qt Quick のbasic レンダリングループを使用しない限り、複数のQQuickWindow インスタンス間で共有しようとすると失敗します。Qt Quick のレンダリングループについての詳細はQt Quick Scene Graphsを参照してください。

注意: Qt Quick のオフスクリーンレンダーパスの結果を含む Texture は、事実上、source プロパティ経由でコンテンツを受け取る Texture が使用するものとは異なる Y 軸方向を持ちます。DefaultMaterial またはPrincipledMaterial と組み合わせて使用する場合、autoOrientation プロパティが true に設定されている限り、必要な UV 変換が自動的に適用されるため、テクスチャがどのようにソースされたかに関係なく、それ以上のアクションは必要ありません。ただし、custom materials を開発する際には、テクスチャをサンプリングして UV 座標を扱う際に、シェーダコード作成者がこの点に留意する必要があります。

source 、textureData 、autoOrientationも参照して ください。


textureData : TextureData

このプロパティは、生のテクスチャデータの内容とプロパティを定義するTextureData コンポーネントへの参照を保持します。

このプロパティを使用すると、source の値は無視されます。テクスチャは、画像データを提供するために 1 つのメソッドを使用し、source、sourceItem 、textureData のいずれか 1 つだけを設定する必要があります。

source,sourceItem,Qt Quick 3D - Procedural Texture Exampleも参照してください 。


textureProvider : RenderExtension [since 6.7]

このプロパティは、このアイテムで使用されるQRhiTexture を提供するRenderExtension を保持します。

注： RenderExtension で作成されたテクスチャは、registering によってエンジンで利用できるようにする必要があります。

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

RenderExtension とQSSGRenderExtensionHelpersも参照して ください。


tilingModeDepth : enumeration

このプロパティは、Z スケーリング値が 1 より大きい場合のテクスチャのマッピング方法を制御します。

デフォルトでは、このプロパティはTexture.Repeat に設定されています。

定数説明
Texture.ClampToEdgeテクスチャはタイル化されず、エッジの値が代わりに使用されます。
Texture.MirroredRepeatテクスチャは Z 軸上で繰り返され、ミラーリングされる。
Texture.Repeatテクスチャは Z 軸上で繰り返されます。

tilingModeHorizontal : enumeration

U スケーリング値が 1 より大きい場合に、テクスチャがどのようにマップされるかを制御します。

デフォルトでは、このプロパティはTexture.Repeat に設定されています。

定数説明
Texture.ClampToEdgeテクスチャはタイル化されず、エッジの値が代わりに使用されます。
Texture.MirroredRepeatテクスチャは X 軸上で繰り返され、ミラーリングされる。
Texture.RepeatテクスチャはX軸上で繰り返される。

scaleUも参照してください 。


tilingModeVertical : enumeration

このプロパティは、V スケーリング値が 1 より大きい場合にテクスチャがどのようにマップされるかを制御します。

デフォルトでは、このプロパティはTexture.Repeat に設定されています。

定数説明
Texture.ClampToEdgeテクスチャはタイル化されず、エッジの値が代わりに使用されます。
Texture.MirroredRepeatテクスチャはY軸上で繰り返され、ミラーリングされる。
Texture.RepeatテクスチャはY軸上で繰り返される。

scaleVも参照してください 。


本書に含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。