Тип QML Canvas

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

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

Свойства

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

Сигналы

• изображениеЗагружено()
• рисование(прямоугольник область)
• отображено()

Методы

• отменитьЗапросAnimationFrame(целое число обработка)
• объект получитьКонтекст(строка идентификаторКонтекста, ... аргументы)
• являетсяОшибкойИзображения(url изображение)
• являетсяИзображениеЗагруженным(url изображение)
• являетсяИзображениеЗагружающимся(url изображение)
• загрузитьИзображение(url изображение)
• пометитьЗагрязненным(прямоугольник область)
• целое число запроситьAnimationFrame(обработчик)
• запроситьРисование()
• логическое значение сохранить(строка имяФайла)
• строка кДаннымURL(строка типMIME)
• разобратьИзображение(url изображение)

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

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

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

В Qt 6.0 элемент Canvas поддерживает одну цель отрисовки: Canvas.Image.

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

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

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

Поддерживаются все операции с пикселями HTML5 2D контекста. Для обеспечения улучшенной производительности чтения/записи пикселей следует выбрать целевой объект отрисовки Canvas.Image.

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

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

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

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

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

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

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

доступно : bool

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также получитьКонтекст() и доступно.

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

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

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

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

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

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

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

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

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

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

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

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

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

изображениеЗагружено()

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

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

См. также загрузитьИзображение().

рисование(прямоугольник область)

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

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

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

painted()

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

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

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

cancelRequestAnimationFrame(int handle)

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

object getContext(string contextId, ... args)

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

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

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

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

isImageError(url image)

Возвращает true , если загрузка изображения image не удалась, и false в противном случае.

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

isImageLoaded(url image)

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

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

isImageLoading(url image)

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

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

loadImage(url image)

Асинхронно загружает указанное изображение image.

После готовности изображения будет испущен сигнал imageLoaded(). Загруженное изображение можно разгрузить с помощью метода unloadImage().

Примечание: На холст можно наносить только загруженные изображения.

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

markDirty(rect area)

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

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

int requestAnimationFrame(callback)

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

requestPaint()

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

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

bool save(string filename)

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

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

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

string toDataURL(string mimeType)

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

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

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

unloadImage(url image)

Разгружает изображение image.

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

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