Тип QML Canvas

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

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

Свойства

• available : bool
• canvasSize : size
• context : object
• contextType : string
• renderStrategy : перечисление
• renderTarget : перечисление

Сигналы

• imageLoaded()
• paint(region)
• painted()

Методы

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

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

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

Поточно-параллельная отрисовка и целевой объект

Элемент Canvas поддерживает два целевых объекта: Canvas.Image и Canvas.FramebufferObject.

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

Целевой объект Canvas.FramebufferObject использует ускорение OpenGL аппаратного обеспечения вместо отрисовки в системной памяти, что во многих случаях приводит к более быстрой отрисовке. Canvas.FramebufferObject использует расширения OpenGL GL_EXT_framebuffer_multisample и GL_EXT_framebuffer_blit для сглаживания. Он также будет использовать больше графической памяти, когда стратегия отрисовки отличается от Canvas.Cooperative. Объекты буфера кадров могут быть недоступны с бэкендами Qt Quick, отличными от OpenGL.

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

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

Поддерживаются все пиксельные операции контекста HTML5 2D. Для обеспечения лучшей производительности при чтении/записи пикселей следует выбрать целевой объект Canvas.Image. Целевой объект Canvas.FramebufferObject требует обмена пиксельными данными между системной памятью и графической картой, что значительно дороже. Отрисовка также может быть синхронизирована с сигналом V-sync (чтобы избежать разрывов изображения на экране), что еще больше повлияет на операции с пикселями с целевым объектом Canvas.FrambufferObject.

Советы по переносу существующих приложений 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 является провайдером текстур и может использоваться напрямую в ShaderEffects и других классах, использующих провайдеры текстур.

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

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

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

available : bool

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

canvasSize : size

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

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

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

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

context : object

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

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

contextType : string

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

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

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

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

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

renderStrategy : enumeration

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

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

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

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

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

См. также renderTarget.

renderTarget : enumeration

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

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

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

По умолчанию целевой объект отрисовки — Canvas.Image.

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

imageLoaded()

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

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

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

paint(region)

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

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

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

painted()

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

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

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

cancelRequestAnimationFrame(handle)

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

object getContext(contextId, ... args)

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

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

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

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

isImageError(image)

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

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

isImageLoaded(image)

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

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

isImageLoading(image)

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

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

loadImage(image)

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

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

Примечание: Только загруженные изображения могут быть нарисованы на элементе Canvas.

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

markDirty(area)

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

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

int requestAnimationFrame(callback)

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

requestPaint()

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

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

bool save(filename)

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

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

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

string toDataURL(mimeType)

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

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

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

unloadImage(image)

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

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

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