이 페이지에서

QRhiTextureSubresourceUploadDescription Class

텍스처 업로드 작업에서 레이어 내 하나의 밉 레벨에 대한 소스를 설명합니다. 더 보기...

헤더: #include <rhi/qrhi.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS GuiPrivate)
target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate)
qmake: QT += gui-private
다음부터: Qt 6.6부터

공개 함수

QRhiTextureSubresourceUploadDescription()
QRhiTextureSubresourceUploadDescription(const QByteArray &data)
QRhiTextureSubresourceUploadDescription(const QImage &image)
QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)
QByteArray data() const
quint32 dataStride() const
QPoint destinationTopLeft() const
QImage image() const
void setData(const QByteArray &data)
void setDataStride(quint32 stride)
void setDestinationTopLeft(const QPoint &p)
void setImage(const QImage &image)
void setSourceSize(const QSize &size)
void setSourceTopLeft(const QPoint &p)
QSize sourceSize() const
QPoint sourceTopLeft() const

상세 설명

소스 콘텐츠는 ` QImage ` 또는 원시 블롭으로 지정됩니다. 전자는 ` QImage`에 매핑될 수 있는 형식의 비압축 텍스처에만 허용되는 반면, 후자는 부동 소수점 및 압축 형식을 포함한 모든 형식에서 지원됩니다.

참고: image()과 data()을 동시에 설정할 수는 없습니다.

destinationTopLeft()는 대상 사각형의 왼쪽 상단 모서리를 지정합니다. 기본값은 (0, 0)입니다.

sourceSize()을 비워두면(기본값) 크기는 하위 리소스의 크기로 간주됩니다. QImage 기반 업로드의 경우, 이는 소스 image()의 크기가 하위 리소스와 일치해야 함을 의미합니다. 대신 원시 데이터를 제공하는 경우, data()에 충분한 바이트 수를 제공해야 합니다.

sourceTopLeft()는 QImage 기반 업로드에서만 지원되며, 소스 사각형의 왼쪽 상단 모서리를 지정합니다.

참고: sourceSize() 또는 sourceTopLeft()를 설정하면 형식과 백엔드에 따라 내부적으로 QImage 복사가 트리거될 수 있습니다.

원시 데이터를 제공하고 setDataStride()을 통해 스트라이드가 지정되지 않은 경우, 제공된 데이터의 스트라이드(행 피치, 바이트 단위의 행 길이)는 width * pixelSize 와 같아야 하며, 여기서 pixelSize 는 픽셀 하나당 사용되는 바이트 수입니다. 또한 행 사이에 추가 패딩이 없어야 합니다. 행 시작 정렬 요건은 없습니다.

입력 원시 데이터의 각 행 끝에 사용되지 않은 데이터가 있는 경우, 행당 총 바이트 수를 지정하여 setDataStride()를 호출하십시오. 스트라이드는 항상 픽셀 1개당 바이트 수의 배수여야 합니다. 행 스트라이드는 비압축 형식의 텍스처에 대한 이미지 데이터에만 적용됩니다.

참고: 소스 데이터의형식은 텍스처 형식과 호환되어야 합니다. 많은 그래픽 API에서 데이터는 있는 그대로 스테이징 버퍼로 복사되며, QRhi 는 중간 형식 변환을 제공하지 않습니다. 이는 부동 소수점 형식에도 적용되며, 예를 들어 RGBA16F의 경우 소스 데이터에 하프 플로트(half float)가 필요합니다.

참고: ` setDataStride()`를 통해 스트라이드를설정하는 기능은 ` QRhi::ImageDataStride `가 ` supported`로 보고될 때만 작동합니다. 실제로는 OpenGL ES 2.0을 제외한 모든 환경에서 이 기능이 지원될 것으로 예상됩니다.

참고: QImage 가지정되면 , QImage::bytesPerLine()에서 반환된 stride가 자동으로 반영됩니다.

경고: QImage 가 지정되었으나 QImage 가 기본 픽셀 데이터를 소유하지 않는경우 , 관련 데이터가 프레임 종료 시까지 유효하게 유지되도록 보장하는 것은 호출자의 책임입니다. (리소스 업데이트 배치를 제출하는 것만으로는 충분하지 않으며, 모든 백엔드에서 이식성을 보장하려면 QRhi::endFrame()가 호출될 때까지 데이터가 유효한 상태를 유지해야 합니다.) 이를 보장할 수 없는 경우, 호출자는 이미지를 uploadTexture()에 전달하기 전에 해당 이미지에 대해 QImage::detach()를 호출할 것을 강력히 권장합니다.

참고: 이는 호환성 보장이 제한적인 RHI API입니다. 자세한 내용은 QRhi 를 참조하십시오.

QRhiTextureUploadDescription도 참조하십시오 .

멤버 함수 문서

[noexcept default] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription()

빈 서브리소스 설명을 생성합니다.

참고: 빈QRhiTextureSubresourceUploadDescription은 그 자체로는 유용하지 않으며, QRhiTextureUploadEntry 에 제출해서는 안 됩니다. 최소한 이미지나 데이터는 먼저 설정되어야 합니다.

[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QByteArray &data)

data 로 지정된 이미지 데이터를 사용하여 밉 레벨 설명을 생성합니다. 이는 부동 소수점 형식 및 압축 형식에도 적합합니다.

[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QImage &image)

image 를 사용하여 밉 레벨 설명을 생성합니다.

` size `의 ` image ` 값은 밉 레벨의 크기와 일치해야 합니다. 레벨 0의 경우 이는 ` texture size`입니다.

image 의 비트 심도는 texture format 와 호환되어야 합니다.

부분 업로드를 처리하려면, setSourceSize(), setSourceTopLeft() 또는 setDestinationTopLeft()을 그 후에 호출하십시오.

QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)

data 및 size 에 지정된 이미지 데이터를 사용하여 밉 레벨 설명을 생성합니다. 이는 부동 소수점 및 압축 형식에도 적합합니다.

data 이 함수가 반환된 후에는 안전하게 소멸시키거나 변경할 수 있습니다.

QByteArray QRhiTextureSubresourceUploadDescription::data() const

현재 설정된 원시 픽셀 데이터를 반환합니다.

setData()도 참조하십시오 .

quint32 QRhiTextureSubresourceUploadDescription::dataStride() const

현재 설정된 데이터 스트라이드를 반환합니다.

setDataStride()도 참조하십시오 .

QPoint QRhiTextureSubresourceUploadDescription::destinationTopLeft() const

현재 설정된 목적지의 왼쪽 상단 위치를 반환합니다. 기본값은 (0, 0)입니다.

setDestinationTopLeft()도 참조하십시오 .

QImage QRhiTextureSubresourceUploadDescription::image() const

현재 설정된 QImage 을 반환합니다.

setImage()도 참조하십시오 .

void QRhiTextureSubresourceUploadDescription::setData(const QByteArray &data)

data 를 설정합니다.

참고: ` image()`와 ` data()`는 동시에 설정할 수 없습니다.

data()도 참조하십시오 .

void QRhiTextureSubresourceUploadDescription::setDataStride(quint32 stride)

데이터 stride 의 바이트 단위를 설정합니다. 기본값은 0이며, 항상 적용되는 것은 아닙니다. 원시 데이터( data())를 제공할 때, setDataStride()를 통해 스트라이드(stride)가 지정되지 않은 경우, 제공된 데이터의 스트라이드(행 간격, 바이트 단위의 행 길이)는 width * pixelSize 와 같아야 합니다. 여기서 pixelSize 는 픽셀 하나당 사용되는 바이트 수이며, 행 사이에 추가적인 패딩이 없어야 합니다. 그렇지 않고 행 사이에 추가 공간이 있는 경우, stride 를 0이 아닌 값으로 설정해야 합니다. 이 모든 사항은 원시 이미지 데이터가 제공될 때만 적용되며, QImage 를 사용할 때는 별도의 stride 값이 있으므로 필요하지 않습니다.

참고: 0이 아닌 stride 가 설정된경우 , 데이터에 마지막 행에 대한 후행 패딩도 포함되어 있는지 확인해야 합니다. 즉, 총 stride * height 바이트 이상이어야 합니다. 마지막 행의 패딩을 제외하고 데이터를 제공하는 것(즉, stride가 마지막 행에는 적용되지 않는 것으로 해석하는 것)은 안전할 수 있으며, 실제로 Vulkan에서는 안전하지만, OpenGL 및 D3D12에서는 실제로 안전하지만, 모든 백엔드에서 이를 보장할 수는 없으므로, 안전한 접근 방식은 이를 피하고 마지막 행도 다른 행과 동일하게 처리하는 것입니다.

참고: setDataStride()를 통해 스트라이드를설정하는 것은 QRhi::ImageDataStride 가 supported 로 보고될 때만 유효합니다.

참고: QImage 가 지정된경우 , QImage::bytesPerLine()에서 반환된 스트라이드가 자동으로 반영되므로 데이터 스트라이드를 수동으로 설정할 필요가 없습니다.

dataStride()도 참조하십시오 .

void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft(const QPoint &p)

p 의 왼쪽 상단 위치를 설정합니다.

참고: QImage 에서 이미지 데이터를 가져오는 가장 일반적인경우 , Qt는 대상 위치와 소스 크기의 합이 대상 텍스처 서브리소스(즉, 지정된 밉 레벨의 크기)의 크기를 초과할 때 유효하지 않은 텍스처 업로드 크기를 클램핑합니다. 이 경우 디버그 출력에 qWarning() 메시지가 표시됩니다. 이는 기본 3D API가 충돌하여 나중에 명령을 제출할 때 GPU 장치가 제거되는 상황을 방지하기 위한 조치입니다. 그럼에도 불구하고, 개발자는 Vulkan, D3D12 또는 Metal의 유효성 검사/디버그 레이어를 활성화한 상태에서 애플리케이션을 실행하여 항상 유효성 검사를 수행할 것을 권장합니다. 이러한 레이어는 API 사용에 대해 훨씬 광범위한 검사를 제공하기 때문입니다.

destinationTopLeft()도 참조하십시오 .

void QRhiTextureSubresourceUploadDescription::setImage(const QImage &image)

image 를 설정합니다. 텍스처가 로드될 때, 이미지 데이터는 형식 변환 없이 있는 그대로 읽힙니다.

참고: image()과 data()은 동시에 설정할 수 없습니다.

image()도 참조하십시오 .

void QRhiTextureSubresourceUploadDescription::setSourceSize(const QSize &size)

size 의 소스 값을 픽셀 단위로 설정합니다.

참고: sourceSize() 또는 sourceTopLeft()를 설정하면 형식과 백엔드에 따라 내부적으로 QImage 복사가 발생할 수 있습니다.

sourceSize()도 참조하십시오 .

void QRhiTextureSubresourceUploadDescription::setSourceTopLeft(const QPoint &p)

소스의 왼쪽 상단 위치를 설정합니다 p.

참고: sourceSize() 또는 sourceTopLeft()을 설정하면 , 형식과 백엔드에 따라 내부적으로 QImage 복사가 트리거될 수 있습니다.

sourceTopLeft()도 참조하십시오 .

QSize QRhiTextureSubresourceUploadDescription::sourceSize() const

소스 크기를 픽셀 단위로 반환합니다. 기본값은 기본 생성된 ` QSize`이며, 이는 전체 서브리소스를 나타냅니다.

setSourceSize()도 참조하십시오 .

QPoint QRhiTextureSubresourceUploadDescription::sourceTopLeft() const

현재 설정된 소스의 왼쪽 상단 위치를 반환합니다. 기본값은 (0, 0)입니다.

setSourceTopLeft()도 참조하십시오 .

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