Тип QML Canvas

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

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

Свойства

• available : bool
• canvasSize : размер
• context : объект
• contextType : строка
• renderStrategy : перечисление
• renderTarget : перечисление

Сигналы

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

Методы

• cancelRequestAnimationFrame(целое handle)
• объект getContext(строка contextId, ... args)
• isImageError(url image)
• isImageLoaded(url image)
• isImageLoading(url image)
• loadImage(url image)
• markDirty(прямоугольник area)
• целое requestAnimationFrame(callback)
• requestPaint()
• bool save(строка filename)
• строка toDataURL(строка 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 поддерживает только контекст 2D-отрисовки.

Потоковая отрисовка и целевой объект отрисовки

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

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

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

По умолчанию целевой объект отрисовки — 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 и других классах, которые используют поставщиков текстур.

См. также Context2D.

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

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 — отрисовка в буфер изображения в памяти.
• Canvas.FramebufferObject — отрисовка в буфер кадра OpenGL

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

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

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

imageLoaded()

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

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

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

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

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

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

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

painted()

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

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

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

cancelRequestAnimationFrame(long handle)

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

object getContext(string 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(rect area)

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

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

long requestAnimationFrame(callback)

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

requestPaint()

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

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

bool save(string filename)

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

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

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

string toDataURL(string mimeType)

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

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

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

unloadImage(url image)

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

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

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