이 페이지에서

QQuickPaintedItem Class

QQuickPaintedItem 클래스는 QML 씬 그래프에서 QPainter API를 사용할 수 있는 방법을 제공합니다. 더 보기...

헤더: #include <QQuickPaintedItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick
상속: QQuickItem

공개 유형

enum PerformanceHint { FastFBOResizing }
flags PerformanceHints
enum RenderTarget { Image, FramebufferObject, InvertedYFramebufferObject }

속성

공개 함수

QQuickPaintedItem(QQuickItem *parent = nullptr)
virtual ~QQuickPaintedItem() override
bool antialiasing() const
QColor fillColor() const
bool mipmap() const
bool opaquePainting() const
virtual void paint(QPainter *painter) = 0
QQuickPaintedItem::PerformanceHints performanceHints() const
QQuickPaintedItem::RenderTarget renderTarget() const
void setAntialiasing(bool enable)
void setFillColor(const QColor &)
void setMipmap(bool enable)
void setOpaquePainting(bool opaque)
void setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true)
void setPerformanceHints(QQuickPaintedItem::PerformanceHints hints)
void setRenderTarget(QQuickPaintedItem::RenderTarget target)
void setTextureSize(const QSize &size)
QSize textureSize() const
void update(const QRect &rect = QRect())

재구현된 공용 함수

virtual bool isTextureProvider() const override
virtual QSGTextureProvider *textureProvider() const override

신호

재구현된 보호 함수

virtual void itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value) override
virtual void releaseResources() override
virtual QSGNode *updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data) override

상세 설명

QQuickPaintedItem을 사용하면 QML 씬 그래프에서 QPainter API를 활용할 수 있습니다. 이 클래스는 씬 그래프 내에 텍스처가 적용된 사각형을 설정하고, QPainter 를 사용하여 텍스처 위에 그림을 그립니다. Qt 6에서 렌더 타겟은 항상 QImage 입니다. 렌더 타겟이 QImage 인 경우, QPainter 는 먼저 이미지에 렌더링한 다음 해당 내용을 텍스처로 업로드합니다. update()를 호출하여 다시 그리기를 트리거합니다.

QPainter 가 앤티앨리어싱 렌더링을 수행하도록 하려면 setAntialiasing()를 사용하십시오.

사용자 정의 페인트 항목을 작성하려면 먼저 QQuickPaintedItem의 서브클래스를 생성한 다음, 실제 페인팅을 구현하는 유일한 순수 가상 공용 함수인 paint()을 구현하는 것으로 시작합니다. 페인팅은 0,0부터 width() 및height()까지를 아우르는 사각형 내부에서 이루어집니다.

참고: 이러한 항목이 유발할 수 있는 성능상의 영향을 이해하는것이 중요합니다 . QQuickPaintedItem::RenderTarget 및 QQuickPaintedItem::renderTarget 을 참조하십시오.

‘씬 그래프 - 페인트된 항목 ’ 및 ‘C++를 사용한 QML 확장 기능 작성’도 참조하십시오 .

멤버 유형 문서

enum QQuickPaintedItem::PerformanceHint
flags QQuickPaintedItem::PerformanceHints

이 열거형은 QQuickPaintedItem 에서 렌더링 성능을 향상시키기 위해 활성화할 수 있는 플래그를 설명합니다. 기본적으로 이 플래그들은 하나도 설정되어 있지 않습니다.

상수값설명
QQuickPaintedItem::FastFBOResizing0x1Qt 6.0부터는 이 값이 무시됩니다.

PerformanceHints 유형은 QFlags<PerformanceHint>에 대한 typedef입니다. 이 유형은 PerformanceHint 값들의 OR 조합을 저장합니다.

enum QQuickPaintedItem::RenderTarget

이 열거형은 QQuickPaintedItem 의 렌더 타겟을 설명합니다. 렌더 타겟은 아이템이 화면에 렌더링되기 전에 QPainter 가 그리는 표면입니다.

상수값설명
QQuickPaintedItem::Image0기본값입니다. QPainter 는 래스터 페인트 엔진을 사용하여 QImage 에 이미지를 그립니다. 이미지의 내용은 나중에 그래픽 메모리로 업로드되어야 하며, 항목이 큰 경우 이 작업이 느려질 수 있습니다. 이 렌더 타겟은 고품질 앤티앨리어싱과 빠른 항목 크기 조정을 지원합니다.
QQuickPaintedItem::FramebufferObject1Qt 6.9부터 이 값은 사용된 렌더링 API가 OpenGL인 경우에만 하드웨어 가속 페인팅을 활성화하며, 그렇지 않은 경우 무시됩니다. Qt 6.0부터 Qt 6.8까지의 버전에서는 모든 렌더링 API에서 이 값이 무시됩니다. 이 경우 일반적으로 렌더링 성능은 향상되지만, 앤티앨리어싱 품질이 저하됩니다.
QQuickPaintedItem::InvertedYFramebufferObject2FramebufferObject와 동일하지만, 렌더링이 X축을 중심으로 반전됩니다.

setRenderTarget()도 참조하십시오 .

속성 설명

fillColor : QColor

이 속성은 항목의 배경 채우기 색상을 지정합니다.

기본적으로 채우기 색상은 Qt::transparent 로 설정되어 있습니다.

배경 채우기를 비활성화하려면 채우기 색상을 유효하지 않은 색상(예: QColor())으로 설정하십시오. 이렇게 하면 성능이 향상될 수 있으며, paint() 함수가 매 프레임마다 모든 픽셀에 그림을 그리는 경우에는 안전하게 수행할 수 있습니다.

액세스 함수:

QColor fillColor() const
void setFillColor(const QColor &)

알림 신호:

void fillColorChanged()

renderTarget : RenderTarget

이 속성은 항목의 렌더 타깃을 지정합니다.

이 속성은 ` QPainter `가 어떤 렌더 타깃으로 렌더링할지 정의하며, ` QQuickPaintedItem::Image`, ` QQuickPaintedItem::FramebufferObject ` 또는 ` QQuickPaintedItem::InvertedYFramebufferObject` 중 하나일 수 있습니다.

각각의 방식에는 특정 장점이 있으며, 일반적으로 성능과 품질의 균형을 고려해야 합니다. 프레임버퍼 객체를 사용하면 그래픽 메모리의 텍스처로 이미지 내용을 업로드하는 데 드는 높은 처리 비용을 피할 수 있는 반면, 이미지를 사용하면 고품질의 앤티앨리어싱이 가능합니다.

경고: 프레임버퍼 객체의 크기조정은 비용이 많이 드는 작업이므로, 항목의 크기가 자주 변경되는 경우 QQuickPaintedItem::FramebufferObject 렌더 타겟 사용을 피하십시오.

기본적으로 렌더 타깃은 QQuickPaintedItem::Image 입니다.

액세스 함수:

QQuickPaintedItem::RenderTarget renderTarget() const
void setRenderTarget(QQuickPaintedItem::RenderTarget target)

알림 신호:

void renderTargetChanged()

textureSize : QSize

텍스처의 크기를 정의합니다.

텍스처 크기를 변경해도 ` paint()`에서 사용되는 좌표계에는 영향을 미치지 않습니다. 대신 배율이 적용되므로, ` width()` 및 `height()` 내에서 여전히 페인팅이 이루어집니다.

기본적으로 텍스처 크기는 이 항목과 동일한 크기를 가집니다.

참고: 아이템이 장치 픽셀 비율이 1과 다른 창에 있는경우 , 이 배율 계수가 텍스처 크기에 암시적으로 적용됩니다.

액세스 함수:

QSize textureSize() const
void setTextureSize(const QSize &size)

알림 신호:

void textureSizeChanged()

멤버 함수 문서

[explicit] QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)

지정된 ` parent ` 항목을 사용하여 `QQuickPaintedItem`을 생성합니다.

[override virtual noexcept] QQuickPaintedItem::~QQuickPaintedItem()

QQuickPaintedItem 를 삭제합니다.

bool QQuickPaintedItem::antialiasing() const

앤티앨리어싱이 활성화된 경우 true를 반환하고, 그렇지 않은 경우 false를 반환합니다.

기본적으로 앤티앨리어싱은 활성화되어 있지 않습니다.

setAntialiasing()도 참조하십시오 .

[override virtual] bool QQuickPaintedItem::isTextureProvider() const

QQuickItem::isTextureProvider() const를 재구현합니다.

[override virtual protected] void QQuickPaintedItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value)

QQuickItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value)를 재구현합니다.

bool QQuickPaintedItem::mipmap() const

미프맵이 활성화되어 있으면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

기본적으로 밉맵핑은 활성화되어 있지 않습니다.

setMipmap()도 참조하십시오 .

bool QQuickPaintedItem::opaquePainting() const

이 아이템이 불투명하면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

기본적으로 페인트 처리된 항목은 불투명하지 않습니다.

setOpaquePainting()도 참조하십시오 .

[pure virtual] void QQuickPaintedItem::paint(QPainter *painter)

일반적으로 QML 씬 그래프에 의해 호출되는 이 함수는 로컬 좌표계에서 항목의 내용을 그립니다.

기본 텍스처의 크기는 textureSize 가 설정된 경우 해당 값으로 정의되거나, 그렇지 않은 경우 항목의 크기에 창의 장치 픽셀 비율을 곱한 값이 됩니다.

이 함수는 항목이 ` fillColor`로 채워진 후에 호출됩니다.

QQuickPaintedItem 의 서브클래스에서 이 함수를 재구현하여 painter 를 사용하여 항목의 페인팅 구현을 제공하십시오.

참고: QML SceneGraph는 두 개의 별도 스레드를 사용합니다. 메인 스레드는 이벤트 처리나 애니메이션 업데이트와 같은 작업을 수행하는 반면, 두 번째 스레드는 그래픽 리소스 업데이트를 실제로 발행하고 드로우 호출을 기록합니다. 결과적으로, paint()는 메인 GUI 스레드에서 호출되는 것이 아니라 GL이 활성화된 렌더러 스레드에서 호출됩니다. paint()가 호출되는 순간 GUI 스레드는 차단되므로, 이 함수는 스레드 안전합니다.

경고: 이 함수 내에서 QObject를 생성하거나, 신호를 발산하거나, 타이머를 시작하는 등의 작업을 수행할 때는각별한 주의를 기울여야 합니다. 이러한 작업은 렌더링 스레드와 밀접한 관련이 있기 때문입니다.

width(), height() 및 textureSize도 참조하십시오 .

QQuickPaintedItem::PerformanceHints QQuickPaintedItem::performanceHints() const

성능 힌트를 반환합니다.

기본적으로 성능 힌트는 활성화되어 있지 않습니다.

setPerformanceHint() 및 setPerformanceHints()도 참조하십시오 .

[override virtual protected] void QQuickPaintedItem::releaseResources()

QQuickItem::releaseResources()을 재구현합니다.

void QQuickPaintedItem::setAntialiasing(bool enable)

enable 가 true인 경우, 앤티앨리어싱이 적용된 그리기가 활성화됩니다.

기본적으로 앤티앨리어싱은 활성화되어 있지 않습니다.

antialiasing()도 참조하십시오 .

void QQuickPaintedItem::setMipmap(bool enable)

enable 가 true인 경우, 해당 텍스처에서 밉매핑이 활성화됩니다.

미핑(Mipmapping)은 아이템의 크기를 축소할 때 렌더링 속도를 높이고 앨리어싱 현상을 줄여줍니다.

기본적으로 밉매핑은 활성화되어 있지 않습니다.

mipmap()도 참조하십시오 .

void QQuickPaintedItem::setOpaquePainting(bool opaque)

opaque 가 true인 경우, 해당 아이템은 불투명하며, 그렇지 않은 경우 반투명하게 간주됩니다.

불투명한 아이템은 나머지 장면과 블렌딩되지 않으므로, 아이템의 내용이 불투명할 경우 렌더링 속도를 높이기 위해 이 값을 true로 설정해야 합니다.

기본적으로 페인트 처리된 아이템은 불투명하지 않습니다.

opaquePainting()도 참조하십시오 .

void QQuickPaintedItem::setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true)

enabled 가 true인 경우, 해당 항목에 지정된 성능 힌트 hint 를 설정하고, 그렇지 않은 경우 성능 힌트를 지웁니다.

기본적으로 성능 힌트는 활성화되어 있지 않습니다.

setPerformanceHints() 및 performanceHints()도 참조하십시오 .

void QQuickPaintedItem::setPerformanceHints(QQuickPaintedItem::PerformanceHints hints)

성능 힌트를 다음과 같이 설정합니다. hints

기본적으로 성능 힌트는 활성화되어 있지 않습니다.

setPerformanceHint() 및 performanceHints()도 참조하십시오 .

[override virtual] QSGTextureProvider *QQuickPaintedItem::textureProvider() const

QQuickItem::textureProvider() const를 재구현합니다.

void QQuickPaintedItem::update(const QRect &rect = QRect())

이 항목에서 ` rect `가 포함하는 영역의 다시 그리기를 예약합니다. 항목의 모양이나 크기가 변경되는 등 다시 그리기가 필요한 경우 언제든지 이 함수를 호출할 수 있습니다.

이 함수는 즉시 그리기를 수행하지 않고, 다음 프레임이 렌더링될 때 QML 씬 그래프에서 처리될 그리기 요청을 예약합니다. 항목은 표시 중인 경우에만 다시 그려집니다.

paint()도 참조하십시오 .

[override virtual protected] QSGNode *QQuickPaintedItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data)

QQuickItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *updatePaintNodeData)를 재구현합니다.

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