Тип QML Canvas

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

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

Свойства

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

Сигналы

• 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 поддерживает только двухмерный контекст рендеринга.

Потоковое рендеринг и целевая область

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

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

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

По умолчанию размер холста такой же, как текущий размер элемента холста.

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

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

context : объект

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

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

contextType : строка

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

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

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

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

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

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

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

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

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

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

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

См. также renderTarget.

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

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

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

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

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

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

imageLoaded()

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

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

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

paint(rect region)

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

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

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

painted()

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

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

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

cancelRequestAnimationFrame(int 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().

int requestAnimationFrame(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.