Canvas QML Type

JavaScript를 통해 그림을 그릴 수 있는 2D 캔버스 항목을 제공합니다. 더 보기...

Import Statement:	`import QtQuick`
Inherits:	Item

속성

available : bool
canvasSize : size
context : object
contextType : string
renderStrategy : enumeration
renderTarget : enumeration

신호

imageLoaded()
paint(rect region)
painted()

방법

cancelRequestAnimationFrame(int handle)
object getContext(string contextId, ... args)
isImageError(url image)
isImageLoaded(url image)
isImageLoading(url image)
loadImage(url image, size sourceSize)
markDirty(rect area)
int requestAnimationFrame(callback)
requestPaint()
bool save(string filename, size imageSize)
string toDataURL(string mimeType)
unloadImage(url image)

상세 설명

캔버스 항목에서는 직선 및 곡선, 단순 및 복잡한 도형, 그래프, 참조 그래픽 이미지를 그릴 수 있습니다. 또한 텍스트, 색상, 그림자, 그라데이션 및 패턴을 추가하고 낮은 수준의 픽셀 작업을 수행할 수 있습니다. 캔버스 출력은 이미지 파일로 저장하거나 URL로 직렬화할 수 있습니다.

캔버스에 대한 렌더링은 일반적으로 paint 신호의 결과인 Context2D 객체를 사용하여 수행됩니다.

캔버스 항목에서 그리기 영역을 정의하려면 width 및 height 속성을 설정합니다. 예를 들어 다음 코드는 높이가 100픽셀, 너비가 200픽셀인 그리기 영역이 있는 캔버스 항목을 만듭니다:

import QtQuick 2.0
Canvas {
    id: mycanvas
    width: 100
    height: 200
    onPaint: {
        var ctx = getContext("2d");
        ctx.fillStyle = Qt.rgba(1, 0, 0, 1);
        ctx.fillRect(0, 0, width, height);
    }
}

현재 캔버스 항목은 2차원 렌더링 컨텍스트만 지원합니다.

스레드 렌더링 및 렌더 대상

Qt 6.0에서 캔버스 항목은 하나의 렌더 타깃을 지원합니다: Canvas.Image.

Canvas.Image 렌더 타겟은 QImage 객체입니다. 이 렌더 타겟은 백그라운드 스레드 렌더링을 지원하므로 복잡하거나 오래 실행되는 페인팅을 UI를 막지 않고 실행할 수 있습니다. 이것은 모든 Qt Quick 백엔드에서 지원되는 유일한 렌더 타겟입니다.

기본 렌더 타겟은 Canvas.Image이고 기본 renderStrategy 은 Canvas.Immediate입니다.

픽셀 연산

모든 HTML5 2D 컨텍스트 픽셀 연산이 지원됩니다. 향상된 픽셀 읽기/쓰기 성능을 보장하려면 Canvas.Image 렌더링 대상을 선택해야 합니다.

기존 HTML5 캔버스 애플리케이션 포팅을 위한 팁

캔버스 항목은 HTML5와 유사한 API를 제공하지만 HTML5 캔버스 애플리케이션을 캔버스 항목에서 실행하려면 수정해야 합니다:

모든 DOM API 호출을 QML 속성 바인딩 또는 캔버스 항목 메서드로 바꿉니다.
모든 HTML 이벤트 핸들러를 MouseArea 항목으로 바꿉니다.
Timer 항목 또는 requestAnimationFrame() 사용으로 setInterval/setTimeout 함수 호출을 변경합니다.
그림 그리기 코드를 onPaint 핸들러에 배치하고 markDirty() 또는 requestPaint() 메서드를 호출하여 그림 그리기를 트리거합니다.
이미지를 그리려면 캔버스의 loadImage() 메서드를 호출하여 이미지를 로드한 다음 onImageLoaded 핸들러에서 페인팅을 요청합니다.

Qt 5.4부터 캔버스는 texture provider 이며 ShaderEffects 및 텍스처 제공자를 사용하는 다른 클래스에서 직접 사용할 수 있습니다.

참고: 일반적으로 큰 캔버스, 빈번한 업데이트 및 애니메이션은 Canvas.Image 렌더 타겟을 사용하지 않는 것이 좋습니다. 가속화된 그래픽 API를 사용하면 업데이트할 때마다 텍스처 업로드가 발생하기 때문입니다. 또한 가능하면 비용이 많이 들고 성능이 떨어지는 JavaScript 및 Context2D 접근 방식 대신 QQuickPaintedItem 을 선호하고 QPainter 을 통해 C++ 로 그리기를 구현하세요.

Context2D, QQuickPaintedItem, Qt Quick 예제 - 포인터 핸들러도참조하세요 .

속성 문서

available : bool [read-only]

캔버스가 작업할 드로잉 컨텍스트를 제공할 수 있는 시기를 나타냅니다.

canvasSize : size

컨텍스트가 그리는 논리적 캔버스 크기를 보유합니다.

기본적으로 캔버스 크기는 현재 캔버스 항목 크기와 같은 크기입니다.

캔버스 크기, 타일 크기 및 캔버스 창을 설정하면 캔버스 항목이 개별적으로 렌더링된 많은 타일 사각형이 있는 큰 가상 캔버스처럼 작동할 수 있습니다. 현재 캔버스 창 내의 타일만 캔버스 렌더링 엔진에 의해 그려집니다.

tileSize 및 canvasWindow 을참조하십시오 .

context : object [read-only]

활성 그리기 컨텍스트를 유지합니다.

캔버스가 준비되고 getContext() 호출이 성공했거나 contextType 속성이 지원되는 컨텍스트 유형으로 설정된 경우 이 속성에는 현재 그리기 컨텍스트가 포함되며, 그렇지 않으면 null이 됩니다.

contextType : string

사용할 드로잉 컨텍스트 유형입니다.

이 속성은 활성 컨텍스트 유형의 이름으로 설정됩니다.

명시적으로 설정하면 캔버스는 사용 가능하게 된 후 명명된 유형의 컨텍스트를 만들려고 시도합니다.

유형 이름은 getContext() 호출에 사용된 것과 동일하며, 2D 캔버스의 경우 값은 "2d"입니다.

getContext() 및 available 을참조하세요 .

renderStrategy : enumeration

현재 캔버스 렌더링 전략을 유지합니다.

Constant	설명
`Canvas.Immediate`	컨텍스트는 메인 UI 스레드에서 그래픽 명령을 즉시 수행합니다.
`Canvas.Threaded`	컨텍스트는 그래픽 명령을 개인 렌더링 스레드로 연기합니다.
`Canvas.Cooperative`	컨텍스트는 그래픽 명령을 애플리케이션의 글로벌 렌더 스레드로 연기합니다.

이 힌트는 렌더링 방법을 결정하기 위해 그래픽 컨텍스트에 renderTarget 와 함께 제공됩니다. 렌더전략, renderTarget 또는 이들의 조합은 그래픽 컨텍스트에서 지원되지 않을 수 있으며, 이 경우 컨텍스트는 적절한 옵션을 선택하고 캔버스는 속성 변경에 대한 신호를 보냅니다.

구성 또는 런타임 테스트로 인해 QML 씬 그래프가 GUI 스레드에서 렌더링될 수 있습니다. Canvas.Cooperative 을 선택해도 렌더링이 GUI 스레드와 분리된 스레드에서 발생한다는 보장은 없습니다.

기본값은 Canvas.Immediate 입니다.

renderTarget 를참조하십시오 .

renderTarget : enumeration

현재 캔버스 렌더링 대상을 보유합니다.

Constant	설명
`Canvas.Image`	인메모리 이미지 버퍼로 렌더링합니다.
`Canvas.FramebufferObject`	Qt 6.0부터 이 값은 무시됩니다.

이 힌트는 renderStrategy 와 함께 그래픽 컨텍스트에 제공되어 렌더링 방법을 결정합니다. renderStrategy , renderTarget 또는 그 조합이 그래픽 컨텍스트에서 지원되지 않을 수 있으며, 이 경우 컨텍스트는 적절한 옵션을 선택하고 캔버스는 속성 변경을 알립니다.

기본 렌더 타겟은 Canvas.Image 입니다.

신호 문서

imageLoaded()

이 신호는 이미지가 로드될 때 발생합니다.

참고: 해당 핸들러는 onImageLoaded 입니다.

loadImage()도 참조하세요 .

paint(rect region)

이 신호는 region 을 렌더링해야 할 때 발생합니다. 컨텍스트가 활성화된 경우 컨텍스트 속성에서 참조할 수 있습니다.

이 신호는 markDirty(), requestPaint() 또는 현재 캔버스 창을 변경하여 트리거할 수 있습니다.

참고: 해당 핸들러는 onPaint 입니다.

painted()

이 신호는 모든 컨텍스트 페인팅 명령이 실행되고 캔버스가 렌더링된 후에 발생합니다.

참고: 해당 핸들러는 onPainted 입니다.

메서드 문서

cancelRequestAnimationFrame(int handle)

이 함수는 handle 에서 참조하는 애니메이션 콜백을 취소합니다.

object getContext(string contextId, ... args)

그리기 컨텍스트를 반환하거나, 컨텍스트가 없는 경우 null 를 반환합니다.

contextId 매개변수는 필요한 컨텍스트의 이름을 지정합니다. 캔버스 항목은 필요한 그리기 모드를 구현하는 컨텍스트를 반환합니다. getContext를 처음 호출한 후 동일한 contextId로 getContext를 후속적으로 호출하면 동일한 컨텍스트 객체가 반환됩니다. 추가 인수(args)는 현재 무시됩니다.

컨텍스트 유형이 지원되지 않거나 캔버스가 이전에 호환되지 않는 다른 컨텍스트 유형을 제공하도록 요청받은 경우 null 가 반환됩니다.

캔버스는 2D 컨텍스트만 지원합니다.

isImageError(url image)

image 로드에 실패한 경우 true, 그렇지 않으면 false 을 반환합니다.

loadImage()도 참조하세요 .

isImageLoaded(url image)

image 가 성공적으로 로드되어 사용할 준비가 되면 true를 반환합니다.

loadImage()도 참조하세요 .

isImageLoading(url image)

image 가 현재 로드 중이면 true를 반환합니다.

loadImage()도 참조하세요 .

loadImage(url image, size sourceSize = undefined)

주어진 image 을 비동기적으로 로드합니다.

이미지가 준비되면 imageLoaded() 신호가 전송됩니다. 로드된 이미지는 unloadImage() 메서드를 사용하여 언로드할 수 있습니다.

참고: 로드된 이미지만 캔버스 항목에 그릴 수 있습니다.

sourceSize 을 지정하면 이미지가 로드되는 동안 해당 크기로 크기가 조정됩니다. 이는 확장 가능한 (벡터) 이미지(예: SVG)를 의도한 표시 크기로 로드할 때 유용합니다. 이 매개변수는 Qt 6.7에 도입되었습니다.

unloadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData() 및 Context2D::drawImage()도 참조하세요 .

markDirty(rect area)

주어진 area 을 더티로 표시하여 이 영역이 표시되면 캔버스 렌더러가 다시 그리도록 합니다. 그러면 paint 신호가 트리거됩니다.

paint 및 requestPaint()도 참조하세요 .

int requestAnimationFrame(callback)

이 함수는 Qt Quick 장면을 구성하기 전에 callback 을 호출하도록 예약합니다.

requestPaint()

보이는 전체 영역을 다시 그리도록 요청합니다.

markDirty()도 참조하세요 .

bool save(string filename, size imageSize = undefined)

현재 캔버스 콘텐츠를 이미지 파일 filename 에 저장합니다. 저장된 이미지 형식은 filename 의 접미사에 의해 자동으로 결정됩니다. 성공하면 true 을 반환합니다. imageSize 을 지정하면 결과 이미지의 크기는 이 크기이며 devicePixelRatio 는 1.0 입니다. 그렇지 않으면 캔버스가 표시되는 창의 devicePixelRatio()가 저장된 이미지에 적용됩니다.

참고: 이 메서드를 호출하면 현재 캔버스에 표시된 창뿐만 아니라 전체 캔버스에 강제로 페인팅됩니다.

canvasWindow, canvasSize, toDataURL()도 참조하세요 .

string toDataURL(string mimeType)

캔버스에 있는 이미지의 데이터 URL을 반환합니다.

기본값 mimeType 은 "image/png"입니다.

save()도 참조하세요 .

unloadImage(url image)

image 을 언로드합니다.

이미지가 언로드되면 다시 로드하지 않는 한 캔버스 컨텍스트에서 이미지를 그릴 수 없습니다.

loadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData() 및 Context2D::drawImage도 참조 하세요.

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