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차원 이미지를 나타냅니다. 일반적으로 3D로 효율적으로 모델링할 수 없는 추가 디테일을 에뮬레이션하기 위해 3차원 지오메트리 위에 매핑하거나 둘러싸는 데 사용됩니다. 또한 리플렉션과 같은 다른 조명 효과를 에뮬레이트하는 데에도 사용할 수 있습니다.

텍스처 자체는 항상 2D 텍스처를 나타내지만, 텍스처의 서브클래스를 통해 다른 종류의 텍스처도 사용할 수 있습니다. 예를 들어 면이 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 - 프로시저럴 텍스처 예시도참조하세요 .

프로퍼티 문서

autoOrientation : bool [since 6.2]

이 속성은 일반적으로 관련된 텍스처에 대해 V 텍스처 좌표 뒤집기와 같은 텍스처 변환이 자동으로 적용되는지 여부를 결정합니다.

기본적으로 이 프로퍼티는 true로 설정됩니다.

source 속성을 통해 .ktx 또는 .pkm 파일에서 로드된 압축 텍스처 또는 sourceItem 속성을 통해 Qt Quick 장면을 렌더링하여 생성된 텍스처와 같은 특정 유형의 텍스처 데이터는 .png 또는 .jpg와 같은 이미지 파일에서 로드된 텍스처와 비교할 때 Y축 방향이 다른 경우가 많습니다. 따라서 이러한 텍스처는 소스가 일반 이미지 파일로 설정된 텍스처와 비교하여 "거꾸로" 나타납니다. 이 문제를 해결하기 위해 모든 적격 텍스처는 flipV 프로퍼티가 true로 설정된 것처럼 암시적 UV 변환을 받습니다. 이를 원하지 않는 경우 이 프로퍼티를 false로 설정합니다.

참고: 이 프로퍼티는 텍스처가 DefaultMaterial 또는 PrincipledMaterial. Custom materials 와 함께 사용될 때 유효하며, 자체 셰이더 코드를 제공하므로 이 프로퍼티로 구성된 것과 같은 변환은 무시되고 애플리케이션에서 제공하는 셰이더 코드에 따라 구현해야 합니다.

이 프로퍼티는 Qt 6.2에 도입되었습니다.

flipV 를참조하십시오 .

flipU : bool

이 프로퍼티는 수평으로 뒤집힌 텍스처 좌표의 사용을 설정합니다.

기본값은 false입니다.

참고: 이 프로퍼티는 텍스처가 DefaultMaterial 또는 PrincipledMaterial. Custom materials 과 함께 사용될 때 유효하며, 자체 셰이더 코드를 제공하므로 이 프로퍼티로 구성된 것과 같은 변환은 무시되고 애플리케이션에서 제공하는 셰이더 코드에 따라 구현해야 합니다.

flipV 를참조하세요 .

flipV : bool

이 속성은 수직으로 뒤집힌 텍스처 좌표의 사용을 설정합니다.

기본값은 false입니다.

참고: 이 프로퍼티는 텍스처가 DefaultMaterial 또는 PrincipledMaterial. Custom materials 과 함께 사용될 때 유효하며, 자체 셰이더 코드를 제공하므로 이 프로퍼티로 구성된 것과 같은 변환은 무시되고 애플리케이션에서 제공하는 셰이더 코드가 구현해야 합니다.

flipU 를참조하세요 .

generateMipmaps : bool

이 프로퍼티는 밉맵 레벨 자체를 제공하지 않는 텍스처에 대해 밉맵을 생성할지 여부를 결정합니다. 밉 필터링과 함께 밉맵을 사용하면 멀리서 텍스처를 볼 때 밉맵이 없는 렌더링에 비해 시각적 품질이 향상되지만 이미지 초기화 시와 렌더링 중 모두 성능 저하가 발생할 수 있습니다.

기본적으로 이 속성은 false로 설정되어 있습니다.

참고: 생성된 밉맵을 사용하려면 mipFilter 모드를 설정해야 합니다.

참고: 텍스처 콘텐츠가 sourceItem 속성에서 참조하는 Qt Quick 항목을 기반으로 하는 경우에는 이 속성을 적용할 수 없습니다. 동적 텍스처에 대한 밉맵 생성은 성능에 영향을 미치기 때문에 불가능합니다. 따라서 이러한 텍스처에 대해서는 이 프로퍼티의 값이 무시됩니다.

mipFilter 를참조하십시오 .

indexUV : int

이 프로퍼티는 이 텍스처가 사용하는 UV 좌표 인덱스를 설정합니다. QtQuick3D 은 현재 2개의 UV 세트(0 또는 1)를 지원하므로 이 값은 해당 범위로 포화됩니다.

기본값은 0입니다.

magFilter : enumeration

이 속성은 텍스처가 "확대", 즉 한 픽셀이 화면 공간에서 두 픽셀 이상을 덮을 때 텍스처가 샘플링되는 방식을 결정합니다.

기본값은 Texture.Linear 입니다.

상수	Description
`Texture.Nearest`	가장 가까운 텍셀의 값을 사용합니다.
`Texture.Linear`	는 가장 가까운 4개의 텍셀을 가져와서 이선 보간합니다.

참고: 여기에 Texture.None 을 사용하면 기본값은 Texture.Linear 이 됩니다.

minFilter 및 mipFilter 을참조하세요 .

mappingMode : enumeration

이 프로퍼티는 이 텍스처를 샘플링할 때 사용할 매핑 방법을 정의합니다.

Constant	설명
`Texture.UV`	기본값입니다. 베이스 컬러, 디퓨즈, 불투명도 및 대부분의 다른 텍스처 맵에 적합합니다. 표준 UV 매핑을 수행합니다. UV 좌표를 변환하고 애니메이션을 적용하지 않는 한 이미지의 동일한 부분이 항상 동일한 버텍스에 나타납니다.
`Texture.Environment`	specular reflection 에 사용하면 이미지가 마치 반사되는 것처럼 머티리얼에 투영됩니다. 다른 유형의 텍스처 맵에 이 모드를 사용하면 미러 효과를 제공합니다.
`Texture.LightProbe`	라이트 프로브에 사용되는 HDRI 구체 맵의 기본값입니다. 이 모드는 lightProbe 프로퍼티와 연결된 텍스처 오브젝트에 대해 자동으로 암시되므로 수동으로 설정할 필요가 없습니다.

minFilter : enumeration

이 속성은 텍스처가 "최소화"된 경우, 즉 텍스처가 화면 공간에서 1픽셀 미만을 차지할 때 샘플링되는 방식을 결정합니다.

기본값은 Texture.Linear 입니다.

Constant	Description
`Texture.Nearest`	가장 가까운 텍셀의 값을 사용합니다.
`Texture.Linear`	는 가장 가까운 4개의 텍셀을 가져와서 이선 보간합니다.

참고: 여기에 Texture.None 을 사용하면 기본값은 Texture.Linear 이 됩니다.

magFilter 및 mipFilter 을참조하세요 .

mipFilter : enumeration

이 속성은 픽셀이 1픽셀 미만을 차지할 때 텍스처 밉맵을 샘플링하는 방법을 결정합니다.

기본값은 Texture.None 입니다.

Constant	Description
`Texture.None`	밉맵 샘플링 사용을 비활성화합니다.
`Texture.Nearest`	밉매핑을 사용하고 가장 가까운 텍셀의 값을 샘플링합니다.
`Texture.Linear`	밉매핑을 사용하며 여러 텍셀 값 사이를 보간합니다.

참고: 이 프로퍼티는 밉맵이 없는 텍스처에는 영향을 미치지 않습니다.

minFilter 및 magFilter 을참조하십시오 .

pivotU : real

이 프로퍼티는 rotationUV 을 적용할 때 사용되는 피벗 U 위치를 설정합니다.

기본값은 0.0입니다.

rotationUV 를참조하세요 .

pivotV : real

이 프로퍼티는 rotationUV 을 적용할 때 사용되는 피벗 V 위치를 설정합니다.

기본값은 0.0입니다.

pivotU 및 rotationUV 을참조하십시오 .

positionU : real

이 속성은 U 좌표 매핑을 왼쪽에서 오른쪽으로 오프셋합니다.

기본값은 0.0입니다.

참고: 이 프로퍼티는 텍스처가 DefaultMaterial 또는 PrincipledMaterial. Custom materials 과 함께 사용될 때 유효하며, 자체 셰이더 코드를 제공하므로 이 프로퍼티로 구성된 것과 같은 변환은 무시되고 애플리케이션에서 제공하는 셰이더 코드에서 구현해야 합니다.

positionV도 참조하십시오 .

positionV : real

이 속성은 V 좌표 매핑을 아래에서 위로 오프셋합니다.

기본값은 0.0입니다.

참고: Qt Quick 3D 은 런타임에 사용되는 그래픽 API에 관계없이 OpenGL 스타일의 버텍스 데이터를 사용합니다. 따라서 UV 위치 (0, 0) 는 이미지 데이터의 왼쪽 하단 모서리를 참조합니다.

참고: 이 프로퍼티는 텍스처가 DefaultMaterial 또는 PrincipledMaterial 와 함께 사용될 때 유효합니다. Custom materials 은 자체 셰이더 코드를 제공하므로 이 프로퍼티로 구성된 것과 같은 변환은 무시되며 애플리케이션에서 제공하는 셰이더 코드에 따라 구현해야 합니다.

positionU도 참조하십시오 .

rotationUV : real

이 프로퍼티는 피벗 포인트를 중심으로 텍스처를 회전합니다. 오일러 각을 사용하여 정의되며 양수 값의 경우 시계 방향으로 회전합니다.

기본값은 0.0입니다.

참고: 이 프로퍼티는 텍스처를 DefaultMaterial 또는 PrincipledMaterial. Custom materials 과 함께 사용할 때 유효하며, 자체 셰이더 코드를 제공하므로 이 프로퍼티로 구성된 것과 같은 변환은 무시되고 애플리케이션에서 제공하는 셰이더 코드에 따라 구현해야 합니다.

pivotU 및 pivotV 을참조하세요 .

scaleU : real

이 프로퍼티는 메시의 UV 좌표에 매핑할 때 U 텍스처 좌표의 스케일을 조정하는 방법을 정의합니다.

수평 타일링을 사용할 때 U 값의 스케일링은 텍스처가 왼쪽에서 오른쪽으로 반복되는 횟수를 정의합니다.

기본값은 1.0입니다.

tilingModeHorizontal 를참조하세요 .

scaleV : real

이 프로퍼티는 메시의 UV 좌표에 매핑할 때 V 텍스처 좌표의 스케일을 조정하는 방법을 정의합니다.

수직 타일링을 사용할 때 V 값의 스케일을 조정하면 텍스처가 아래에서 위로 반복되는 횟수를 정의할 수 있습니다.

기본값은 1.0입니다.

참고: 이 프로퍼티는 텍스처가 DefaultMaterial 또는 PrincipledMaterial. Custom materials 과 함께 사용될 때 유효하므로 이 프로퍼티로 구성된 것과 같은 변환은 무시되고 애플리케이션에서 제공하는 셰이더 코드에서 구현해야 합니다.

tilingModeVertical 를참조하세요 .

source : url

이 속성은 텍스처에 사용되는 데이터가 포함된 이미지 또는 텍스처 파일의 위치를 보유합니다.

이 프로퍼티는 URL이며 Image.source 와 같은 다른 소스 프로퍼티와 동일한 규칙이 적용됩니다. 텍스처의 경우 qrc 및 file 스키마만 지원됩니다. 스키마가 없고 값이 상대 경로인 경우 컴포넌트(즉, .qml 파일)의 위치에 상대적인 것으로 간주됩니다.

소스 파일은 일반적인 이미지 파일 형식 supported by Qt 을 사용할 수 있습니다. 또한 텍스처는 QtQuick::Image와 동일한 compressed texture file types 을 지원합니다.

참고: .png 또는 .jpg와 같은 이미지 파일에서 읽은 텍스처 데이터는 텍스처 내의 픽셀 행을 Qt Quick 3D 렌더링 엔진에 정의된 순서대로 저장하는 작업을 포함합니다. 소스 파일이 압축된 텍스처 데이터의 컨테이너인 경우 이러한 변환은 픽셀 데이터 수준에서 이루어질 수 없습니다. .ktx 또는 .pkm 파일이 그 예입니다. 대신 텍스처는 화면에서 동일한 결과를 얻기 위해 조각 셰이더 코드에서 암시적으로 수직 뒤집기를 활성화합니다. 이는 autoOrientation 속성으로 제어되며 원하는 경우 비활성화할 수 있습니다.

참고: 일부 텍스처 압축 도구는 이미지 데이터에 자동 수직 미러링(뒤집기)을 적용할 수 있습니다. 최신 도구에서는 이 설정이 옵트인 설정인 경우가 많습니다. 예기치 않게 뒤집힌 텍스처로 인해 오브젝트의 텍스처링이 잘못되는 경우 애플리케이션과 렌더링 엔진의 제어 범위를 벗어난 에셋 자체에 근본 원인이 있을 수 있으므로 에셋 조절 파이프라인에서 사용되는 설정을 잘 파악하는 것이 중요합니다. 에셋에 필요한 경우 애플리케이션은 언제든지 flipV 프로퍼티를 직접 설정할 수 있습니다.

sourceItem, textureData, autoOrientation, flipV 을참조하세요 .

sourceItem : Item

이 프로퍼티는 텍스처의 소스로 사용할 Item을 정의합니다. 이 속성을 사용하면 해당 항목을 오프스크린 레이어로 렌더링하여 2D Qt Quick 콘텐츠를 텍스처 소스로 사용할 수 있습니다.

항목이 texture provider 인 경우 추가 텍스처가 사용되지 않습니다.

이 프로퍼티가 설정되어 있으면 source 값은 무시됩니다. 텍스처는 이미지 데이터를 제공하는 데 한 가지 메서드를 사용해야 하며 소스, sourceItem 또는 textureData 중 하나만 설정해야 합니다.

참고: 현재 입력 이벤트는 사용자가 한 번에 하나의 sourceItem 인스턴스와만 상호 작용하도록 제한되는 경우에만 텍스처 소스로 사용되는 Item으로 전달됩니다. 즉, 여러 텍스처 간에 동일한 아이템을 공유할 수는 있지만 동시에 여러 텍스처에서 동일한 아이템과 멀티터치 상호작용을 할 수는 없습니다. 따라서 내부에서 인터랙티브한 아이템을 조작하려면 각 텍스처 인스턴스마다 별도의 2D 서브씬 인스턴스를 사용하는 것이 가장 좋습니다.

참고: 여러 창에서 참조되는 텍스처에서 이 프로퍼티를 사용하는 것은 권장하지 않습니다. 여기에는 View3D::importScene 을 통한 사용도 포함됩니다. Qt Quick 이 프로퍼티로 생성된 소스 텍스처는 하나의 렌더 스레드에서만 액세스할 수 있으므로 기본 threaded 대신 basic 렌더 루프가 사용되지 않는 한 여러 QQuickWindow 인스턴스 간에 공유를 시도하면 실패할 수 있습니다. Qt Quick 렌더 루프에 대한 자세한 내용은 Qt Quick 씬 그래프를 참조하세요.

참고: Qt Quick 오프스크린 렌더 패스의 결과를 포함하는 텍스처는 소스 프로퍼티를 통해 콘텐츠를 수신하는 텍스처가 사용하는 것과는 다른 Y축 방향을 갖게 됩니다. DefaultMaterial 또는 PrincipledMaterial 과 함께 사용하면 autoOrientation 프로퍼티가 true로 설정되어 있으면 필요한 UV 변환이 자동으로 적용되므로 텍스처 소싱 방식에 관계없이 추가 작업이 필요하지 않습니다. 그러나 custom materials 개발 시 셰이더 코드 작성자는 텍스처를 샘플링하고 UV 좌표로 작업할 때 이 점을 염두에 두어야 합니다.

source, textureData, autoOrientation 를참조하세요 .

textureData: TextureData

이 프로퍼티는 원시 텍스처 데이터의 내용과 속성을 정의하는 TextureData 컴포넌트에 대한 참조를 보유합니다.

이 속성을 사용하면 source 값은 무시됩니다. 텍스처는 이미지 데이터를 제공하는 데 한 가지 방법을 사용해야 하며 소스, sourceItem, 또는 textureData 중 하나만 설정해야 합니다.

source, sourceItem, Qt Quick 3D - 프로시저럴 텍스처 예시도참조하세요 .

textureProvider : RenderExtension [since 6.7]

이 프로퍼티는 이 항목에서 사용할 QRhiTexture 을 제공할 RenderExtension 을 보유합니다.

참고: RenderExtension 에서 생성된 텍스처는 엔진에서 registering 에서 사용할 수 있도록 설정해야 합니다.

이 프로퍼티는 Qt 6.7에 도입되었습니다.

RenderExtension 및 QSSGRenderExtensionHelpers 을참조하십시오 .

tilingModeDepth : enumeration

이 프로퍼티는 Z 스케일링 값이 1보다 클 때 텍스처가 매핑되는 방식을 제어합니다.

기본적으로 이 프로퍼티는 Texture.Repeat 로 설정되어 있습니다.

Constant	설명
`Texture.ClampToEdge`	텍스처가 타일링되지 않고 가장자리의 값이 대신 사용됩니다.
`Texture.MirroredRepeat`	텍스처가 Z 축에 걸쳐 반복되고 미러링됩니다.
`Texture.Repeat`	텍스처가 Z 축을 따라 반복됩니다.

tilingModeHorizontal : enumeration

U 스케일링 값이 1보다 클 때 텍스처가 매핑되는 방식을 제어합니다.

기본적으로 이 프로퍼티는 Texture.Repeat 로 설정됩니다.

Constant	설명
`Texture.ClampToEdge`	텍스처가 타일링되지 않고 가장자리의 값이 대신 사용됩니다.
`Texture.MirroredRepeat`	텍스처가 X 축에 반복되고 미러링됩니다.
`Texture.Repeat`	텍스처가 X 축을 따라 반복됩니다.

scaleU 를참조하십시오 .

tilingModeVertical : enumeration

이 속성은 V 스케일링 값이 1보다 클 때 텍스처가 매핑되는 방식을 제어합니다.

기본적으로 이 프로퍼티는 Texture.Repeat 로 설정됩니다.

Constant	설명
`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.