Тип Canvas QML

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

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

Свойства

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

Сигналы

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

Методы

• cancelRequestAnimationFrame(int handle)
• object getContext(string contextId, ... args)
• isImageError(url image)
• isImageLoaded(url image)
• isImageLoading(url image)
• loadImage(url image)
• markDirty(прямоугольник area)
• int requestAnimationFrame(callback)
• requestPaint()
• bool save(string filename)
• string toDataURL(string mimeType)
• unloadImage(url 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:

• Замените все вызовы API DOM на привязки свойств 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 : перечисление

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

• 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. Если активен контекст, к нему можно обратиться через свойство context.

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

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

painted()

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

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

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

cancelRequestAnimationFrame(целое handle)

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

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

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

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

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

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

isImageError(url image)

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

См. также 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.

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

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

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

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

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

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

unloadImage(url image)

Разгружает image.

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

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