Тип QML Canvas

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

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

Свойства

• available : bool
• canvasSize : размер
• контекст : объект
• типКонтекста : строка
• стратегияОтрисовки : перечисление
• цельОтрисовки : перечисление

Сигналы

• imageLoaded()
• рисунок(область)
• нарисовано()

Методы

• cancelRequestAnimationFrame(обработка)
• объект getContext(contextId, ... args)
• естьОшибкаИзображения(изображение)
• изображениеЗагружено(изображение)
• изображениеЗагружается(изображение)
• загрузитьИзображение(изображение)
• пометитьЗагрязнённым(область)
• целое requestAnimationFrame(обработчик)
• запроситьРисунок()
• логическое сохранить(имяФайла)
• строка toDataURL(mimeType)
• разгрузитьИзображение(изображение)

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

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

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

Чтобы определить область рисования в элементе 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, а по умолчанию стратегия отрисовки — Canvas.Immediate.

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

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

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

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

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

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

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

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

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

доступно : bool

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

размерХолста : размер

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

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

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

См. также размерПлитки и окноХолста.

контекст : объект

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

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

типКонтекста : строка

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

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

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

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

См. также getContext() и доступно.

стратегияОтрисовки : перечисление

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

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

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

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

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

См. также цельОтрисовки.

цельОтрисовки : перечисление

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

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

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

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

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

imageLoaded()

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

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

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

paint(region)

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

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

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

painted()

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

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

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

cancelRequestAnimationFrame(handle)

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

object getContext(contextId, ... args)

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

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

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

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

isImageError(image)

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

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

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

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

string toDataURL(mimeType)

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

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

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

unloadImage(image)

Разгрузить image.

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

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