Тип QML Canvas

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

• Список всех членов, включая унаследованные
• Устаревшие члены

Свойства

• 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 позволяет рисовать прямые и кривые линии, простые и сложные фигуры, графики и ссылочные графические изображения. Он также может добавлять текст, цвета, тени, градиенты и узоры, а также выполнять низкоуровневые операции с пикселями. Вывод Canvas можно сохранить как изображение или сериализовать в URL.

Отрисовка на Canvas выполняется с использованием объекта 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.

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

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

Рекомендации по переносу существующих приложений HTML5 Canvas

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

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

Начиная с Qt 5.4, Canvas является поставщиком текстур и может быть использован напрямую в 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 холста значение будет "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 графическому контексту для определения метода отрисовки. Стратегия отрисовки, целевая область или их комбинация могут не поддерживаться графическим контекстом, в этом случае контекст выберет подходящие параметры, и 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.