Тип QML Canvas

Предоставляет элемент холста 2D, позволяющий рисовать с помощью JavaScript. Подробнее...

Заявление об импорте:	import QtQuick
С момента:	Qt 5.0
Наследует:	Item

Свойства

available : bool
canvasSize : размер
context : объект
contextType : строка
renderStrategy : перечисление
renderTarget : перечисление

Сигналы

imageLoaded()
paint(прямоугольник region)
painted()

Методы

cancelRequestAnimationFrame(int handle)
объект getContext(строка contextId, ... args)
isImageError(url image)
isImageLoaded(url image)
isImageLoading(url image)
loadImage(url image)
markDirty(прямоугольник area)
int requestAnimationFrame(callback)
requestPaint()
bool save(строка filename)
строка toDataURL(строка mimeType)
unloadImage(url image)

Подробное описание

Элемент Canvas позволяет рисовать прямые и кривые линии, простые и сложные фигуры, графики и изображения графических изображений. Он также может добавлять текст, цвета, тени, градиенты и узоры, а также выполнять операции с пикселями на низком уровне. Вывод холста можно сохранить как изображение файла или сериализовать в URL.

Отрисовка на холсте выполняется с помощью объекта Context2D, обычно в результате сигнала paint.

Чтобы определить область рисования на элементе Canvas, установите свойства width и height. Например, следующий код создает элемент Canvas, у которого область рисования имеет высоту 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);
    }
}

В настоящее время элемент Canvas поддерживает только двухмерный контекст отрисовки.

Потоковая отрисовка и целевой объект

В Qt 6.0 элемент Canvas поддерживает один целевой объект: Canvas.Image.

Целевой объект Canvas.Image — это объект QImage. Этот целевой объект поддерживает отрисовку в фоновом потоке, позволяя выполнять сложные или длительные операции рисования без блокировки пользовательского интерфейса. Это единственный целевой объект, поддерживаемый всеми бэкендами Qt Quick.

По умолчанию целевой объект — Canvas.Image, а по умолчанию renderStrategy — Canvas.Immediate.

Операции с пикселями

Поддерживаются все операции с пикселями контекста 2D HTML5. Чтобы обеспечить улучшенную производительность чтения/записи пикселей, следует выбрать целевой объект Canvas.Image.

Советы по портированию существующих приложений HTML5 Canvas

Хотя элемент Canvas предоставляет API, похожий на HTML5, приложениям HTML5 canvas необходимо внести изменения для работы в элементе Canvas:

Замените все вызовы DOM API на привязки свойств QML или методы элемента Canvas.
Замените все обработчики событий HTML на элемент MouseArea.
Измените вызовы функций setInterval/setTimeout на элемент Timer или используйте requestAnimationFrame().
Разместите код рисования в обработчик onPaint и запустите отрисовку, вызвав методы markDirty() или requestPaint().
Чтобы нарисовать изображения, загрузите их, вызвав метод loadImage() Canvas, а затем запросите их отрисовку в обработчике onImageLoaded.

Начиная с Qt 5.4, Canvas является поставщиком текстур qsgtextureprovider и может использоваться непосредственно в ShaderEffects и других классах, которые используют поставщиков текстур.

Примечание: В целом, следует избегать больших холстов, частых обновлений и анимации с целевым объектом Canvas.Image. Это связано с тем, что при использовании ускорений графических API каждое обновление приведет к загрузке текстуры. Кроме того, по возможности, предпочтительнее использовать QQuickPaintedItem и реализовать рисование на C++ с помощью QPainter вместо более дорогостоящего и, вероятно, менее производительного подхода на JavaScript и Context2D.

См. также Context2D и QQuickPaintedItem.

Документация по свойствам

available : bool

Указывает, когда Canvas может предоставить контекст рисования для работы.

canvasSize : размер

Содержит логический размер холста, на котором рисует контекст.

По умолчанию размер холста совпадает с текущим размером элемента холста.

Устанавливая canvasSize, tileSize и canvasWindow, элемент Canvas может действовать как большой виртуальный холст со многими отдельными прямоугольниками плиток. Только те плитки, которые находятся в текущем окне холста, рисуются движком отрисовки Canvas.

См. также tileSize и canvasWindow.

context : объект

Содержит активный контекст рисования.

Если холст готов и успешно был вызван getContext() или свойство contextType было установлено с поддерживаемым типом контекста, это свойство будет содержать текущий контекст рисования, в противном случае null.

contextType : строка

Тип контекста рисования для использования.

Это свойство устанавливается в имя активного типа контекста.

Если оно явно установлено, холст попытается создать контекст указанного типа после того, как станет доступным.

Имя типа такое же, как используется в вызове getContext(), для двухмерного холста значением будет "2d".

См. также getContext() и available.

renderStrategy : перечисление

Содержит текущую стратегию отрисовки холста.

Canvas.Immediate - контекст выполнит команды графики немедленно в основном потоке пользовательского интерфейса.
Canvas.Threaded - контекст отложит команды графики в отдельный поток отрисовки.
Canvas.Cooperative - контекст отложит команды графики в глобальный поток отрисовки приложения.

Этот подсказка предоставляется вместе с renderTarget графическому контексту, чтобы определить способ отрисовки. Стратегия отрисовки, renderTarget или их комбинация могут не поддерживаться графическим контекстом, в этом случае контекст выберет соответствующие варианты, и Canvas сообщит об изменениях в свойствах.

Конфигурация или тесты во время выполнения могут привести к тому, что QML Scene Graph будет отрисовываться в потоке GUI. Выбор Canvas.Cooperative, не гарантирует, что отрисовка будет происходить в отдельном потоке от потока GUI.

Значение по умолчанию — Canvas.Immediate.

См. также renderTarget.

renderTarget : перечисление

Содержит текущий целевой объект отрисовки холста.

Canvas.Image - отрисовка в буфер изображения в памяти.

Этот подсказка предоставляется вместе с renderStrategy графическому контексту, чтобы определить способ отрисовки. Стратегия отрисовки, renderTarget или их комбинация могут не поддерживаться графическим контекстом, в этом случае контекст выберет соответствующие варианты, и Canvas сообщит об изменениях в свойствах.

Целевой объект по умолчанию — Canvas.Image.

Документация по сигналам

imageLoaded()

Этот сигнал испускается, когда изображение загружено.

Примечание: Соответствующий обработчик — onImageLoaded.

См. также loadImage().

paint(прямоугольник region)

Этот сигнал испускается, когда нужно отрисовать region. Если контекст активен, к нему можно обратиться через свойство context.

Этот сигнал может быть вызван методами markdirty(), requestPaint() или изменением текущего окна холста.

Примечание: Соответствующий обработчик — onPaint.

painted()

Этот сигнал генерируется после выполнения всех команд отрисовки контекста и отрисовки холста.

Примечание: Соответствующий обработчик — onPainted.

Документация по методам

cancelRequestAnimationFrame(int handle)

Эта функция отменяет вызов анимации, на который ссылается handle.

object getContext(string contextId, ... args)

Возвращает контекст рисования или null в случае отсутствия контекста.

Параметр contextId задаёт необходимый контекст. Элемент холста вернёт контекст, реализующий необходимый режим рисования. После первого вызова getContext, любой последующий вызов getContext с тем же contextId вернёт тот же объект контекста. Любые дополнительные аргументы (args) в настоящее время игнорируются.

Если тип контекста не поддерживается или холст ранее был запрошен для предоставления другого несовместимого типа контекста, будет возвращено значение null.

Холст поддерживает только 2D-контекст.

isImageError(url image)

Возвращает true если загрузка изображения image завершилась ошибкой, false в противном случае.

См. также loadImage().

isImageLoaded(url image)

Возвращает true, если изображение image успешно загружено и готово к использованию.

См. также loadImage().

isImageLoading(url image)

Возвращает true, если изображение image загружается в данный момент.

См. также loadImage().

loadImage(url image)

Асинхронно загружает заданное изображение image.

После готовности изображения будет выпущен сигнал imageLoaded(). Загруженное изображение можно выгрузить методом unloadImage().

Примечание: На холст можно наносить только загруженные изображения.

См. также unloadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData() и Context2D::drawImage().

markDirty(rect area)

Отмечает заданную область area как повреждённую, поэтому при отображении этой области рендерер холста перерисует её. Это вызовет сигнал paint.

См. также paint и requestPaint().

int requestAnimationFrame(callback)

Эта функция планирует вызов callback перед составлением сцены Qt Quick.

requestPaint()

Запрашивает повторную отрисовку всей видимой области.

См. также markDirty().

bool save(string filename)

Сохраняет содержимое текущего холста в файл изображения filename. Формат сохраняемого изображения автоматически определяется по расширению файла filename. При успехе возвращает true.

Примечание: Вызов этого метода заставит перерисовать весь холст, а не только текущее видимое окно холста.

См. также canvasWindow, canvasSize и toDataURL().

string toDataURL(string mimeType)

Возвращает URL данных для изображения на холсте.

По умолчанию mimeType — "image/png".

См. также save().

unloadImage(url image)

Выгружает изображение image.

После выгрузки изображение не может быть нарисовано контекстом холста, пока оно не будет загружено снова.

См. также loadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData() и Context2D::drawImage.

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-6.2/qml-qtquick-canvas.html