Texture QML Type

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

Import Statement:	`import QtQuick3D`
Inherits:	Object3D
Inherited By:	CubeMapTexture

継承されたメンバを含む、すべてのメンバのリスト

プロパティ

autoOrientation : bool (since 6.2)
flipU : bool
flipV : bool
generateMipmaps : bool
indexUV : int
magFilter : enumeration
mappingMode : enumeration
minFilter : enumeration
mipFilter : enumeration
pivotU : real
pivotV : real
positionU : real
positionV : real
rotationUV : real
scaleU : real
scaleV : real
source : url
sourceItem : Item
textureData : TextureData
textureProvider : RenderExtension (since 6.7)
tilingModeDepth : enumeration
tilingModeHorizontal : enumeration
tilingModeVertical : enumeration

詳細説明

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

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

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

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

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

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

source プロパティを使用した、イメージまたはテクスチャファイル、
sourceItem プロパティを使用して、Qt Quick Item 、
または、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.Environment`	specular 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 : real

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

デフォルトは 0.0 です。

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

rotationUVも参照してください。

pivotV : real

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

デフォルトは 0.0 です。

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

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

positionU : real

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

デフォルトは 0.0 です。

positionVも参照してください。

positionV : real

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

デフォルトは 0.0 です。

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

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

positionUも参照してください。

rotationUV : real

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

デフォルトは 0.0 です。

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

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

scaleU : real

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

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

デフォルトは1.0です。

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

tilingModeHorizontalも参照してください。

scaleV : real

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

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

デフォルトは1.0です。

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

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

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

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

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

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

注意: Qt Quick オフスクリーンレンダーパスの結果を含む Texture は、事実上、ソースプロパティ経由でそのコンテンツを受け取る 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も参照。

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