Тип QML Canvas

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

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

Свойства

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

Сигналы

• 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)
• markDirty(rect area)
• int requestAnimationFrame(callback)
• requestPaint()
• bool save(string filename)
• string toDataURL(string 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 поддерживает только двумерный контекст отрисовки.

Многопоточная отрисовка и целевой объект

Элемент 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:

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

Начиная с Qt 5.4, холст является поставщиком текстур и может использоваться напрямую в 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 : перечисление

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

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

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

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

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

См. также renderTarget.

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

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

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

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

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

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

imageLoaded()

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

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

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

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

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

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

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

painted()

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

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

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

cancelRequestAnimationFrame(целое handle)

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

объект getContext(строка contextId, ... args)

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

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

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

Canvas поддерживает только 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().

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

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

markDirty(прямоугольник area)

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

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

целое requestAnimationFrame(callback)

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

requestPaint()

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

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

булево save(строка filename)

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

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

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

строка toDataURL(строка mimeType)

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

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

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

unloadImage(url image)

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

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

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