Тип QML Canvas

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

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

Свойства

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

Сигналы

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

Методы

• cancelRequestAnimationFrame(int handle)
• объект getContext(строка contextId, ... args)
• isImageError(url image)
• isImageLoaded(url image)
• isImageLoading(url image)
• loadImage(url image)
• markDirty(прямоугольник area)
• int 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. Эта цель отрисовки поддерживает отрисовку в фоновом потоке, что позволяет выполнять сложную или длительную отрисовку без блокировки пользовательского интерфейса. Это единственная цель отрисовки, поддерживаемая всеми бэкендами 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.

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

Поддерживаются все пиксельные операции контекста 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 на элемент Таймер или использование 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 : размер

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

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

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

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

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

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

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

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

Тип контекста рисования, который нужно использовать.

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

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

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

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

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

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

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

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

Конфигурационные или runtime-тесты могут привести к тому, что 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()

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

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

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

cancelRequestAnimationFrame(целое handle)

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

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

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

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

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

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