Класс QTransform

Класс QTransform задаёт 2D преобразования системы координат. Подробнее...

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

Открытые типы

Открытые функции

Статические публичные члены

Связанные нечлены

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

Класс QTransform определяет 2D преобразования системы координат.

Преобразование определяет, как перевести, масштабировать, наклонить, повернуть или спроецировать систему координат и обычно используется при отрисовке графики.

QTransform отличается от QMatrix тем, что представляет собой истинную 3x3 матрицу, позволяющую проводить перспективные преобразования. Метод toAffine() класса QTransform позволяет преобразовать QTransform в QMatrix. Если в матрице задано перспективное преобразование, то преобразование приведет к потере данных.

QTransform является рекомендуемым классом преобразований в Qt.

Объект QTransform может быть создан с помощью функций setMatrix(), scale(), rotate(), translate() и shear(). В качестве альтернативы, он может быть создан путём применения основных операций с матрицей. Матрица также может быть определена при создании объекта, и она может быть сброшена до единичной матрицы (по умолчанию) с помощью функции reset().

Класс QTransform поддерживает отображение графических примитивов: заданная точка, линия, многоугольник, область или траектория рисования могут быть отображены в системе координат, заданной данной матрицей, с помощью функции map(). В случае прямоугольника его координаты могут быть преобразованы с помощью функции mapRect(). Прямоугольник также может быть преобразован в многоугольник (отображён в системе координат, заданной этой матрицей) с помощью функции mapToPolygon().

QTransform предоставляет функцию isIdentity(), которая возвращает true если матрица является единичной матрицей, и функцию isInvertible(), которая возвращает true если матрица является невырожденной (т. е. AB = BA = I). Функция inverted() возвращает инвертированную копию данной матрицы, если она обратима (в противном случае возвращает единичную матрицу), а функция adjoint() возвращает классическую присоединённую матрицу. Кроме того, QTransform предоставляет функцию determinant(), которая возвращает определитель матрицы.

Наконец, класс QTransform поддерживает умножение, сложение и вычитание матриц, а также объекты этого класса могут быть сериализованы и сравниваются.

Отрисовка графики

При отрисовке графики матрица определяет преобразования, но фактическое преобразование выполняется процедурами отрисовки в QPainter.

По умолчанию, QPainter работает в собственной системе координат связанного устройства. Стандартная система координат QPaintDevice имеет начало отсчета в верхнем левом углу. Значения x увеличиваются вправо; значения y увеличиваются вниз. Более подробная информация представлена в документации по системе координат.

QPainter имеет функции для перемещения, масштабирования, наклона и поворота системы координат без использования QTransform. Например:

void SimpleTransformation::paintEvent(QPaintEvent *) { QPainter painter(this); painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); painter.drawRect(0, 0, 100, 100); painter.rotate(45); painter.setFont(QFont("Helvetica", 24)); painter.setPen(QPen(Qt::black, 1)); painter.drawText(20, 10, "QTransform"); }

Хотя эти функции очень удобны, может быть эффективнее создать QTransform и вызвать QPainter::setTransform(), если вы хотите выполнить более одной операции преобразования. Например:

void CombinedTransformation::paintEvent(QPaintEvent *) { QPainter painter(this); painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); painter.drawRect(0, 0, 100, 100); QTransform transform; transform.translate(50, 50); transform.rotate(45); transform.scale(0.5, 1.0); painter.setTransform(transform); painter.setFont(QFont("Helvetica", 24)); painter.setPen(QPen(Qt::black, 1)); painter.drawText(20, 10, "QTransform"); }

Основные операции с матрицей

Объект QTransform содержит матрицу 3x3. Элементы m31 (dx) и m32 (dy) задают горизонтальное и вертикальное смещение. Элементы m11 и m22 задают горизонтальное и вертикальное масштабирование. Элементы m21 и m12 задают горизонтальное и вертикальное сдвижение. И, наконец, элементы m13 и m23 задают горизонтальную и вертикальную проекцию, при этом m33 является дополнительным коэффициентом проекции.

QTransform преобразует точку на плоскости в другую точку, используя следующие формулы:

x' = m11*x + m21*y + dx
y' = m22*y + m12*x + dy
if (is not affine) {
    w' = m13*x + m23*y + m33
    x' /= w'
    y' /= w'
}

Точка (x, y) — исходная точка, а (x', y') — преобразованная точка. (x', y') можно преобразовать обратно в (x, y), выполнив ту же операцию над обращённой() матрицей.

Различные элементы матрицы можно установить при создании матрицы или с помощью функции setMatrix() позже. Их также можно изменить с помощью удобных функций translate(), rotate(), scale() и shear(). Текущие значения можно получить с помощью функций m11(), m12(), m13(), m21(), m22(), m23(), m31(), m32(), m33(), dx() и dy().

Смещение — это самое простое преобразование. Установка значений dx и dy переместит систему координат на dx единиц по оси X и dy единиц по оси Y.

Масштабирование выполняется путём установки значений m11 и m22. Например, установка m11 в 2 и m22 в 1.5 удвоит высоту и увеличит ширину на 50%. Единичная матрица имеет m11, m22, и m33 равные 1 (все остальные равны 0), отображая точку на себя.

Сдвиг контролируется элементами m12 и m21. Установка этих элементов в значения, отличные от нуля, повернёт систему координат.

Поворот достигается установкой коэффициентов сдвига и масштабирования. Преобразование перспективы достигается установкой коэффициентов проекции и коэффициентов масштабирования.

Вот пример комбинированных преобразований с использованием основных операций с матрицами:

void BasicOperations::paintEvent(QPaintEvent *) { double pi = 3.14; double a = pi/180 * 45.0; double sina = sin(a); double cosa = cos(a); QTransform translationTransform(1, 0, 0, 1, 50.0, 50.0); QTransform rotationTransform(cosa, sina, -sina, cosa, 0, 0); QTransform scalingTransform(0.5, 0, 0, 1.0, 0, 0); QTransform transform; transform = scalingTransform * rotationTransform * translationTransform; QPainter painter(this); painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); painter.drawRect(0, 0, 100, 100); painter.setTransform(transform); painter.setFont(QFont("Helvetica", 24)); painter.setPen(QPen(Qt::black, 1)); painter.drawText(20, 10, "QTransform"); }

См. также QPainter, Система координат, Пример аффинных преобразований и Пример преобразований.

Документация типов членов

перечисление QTransform::TransformationType

Документация функций-членов

QTransform::QTransform()

Создаёт единичную матрицу.

Все элементы установлены в ноль, за исключением m11 и m22 (определяющих масштаб) и m33, которые установлены в 1.

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

QTransform::QTransform(qreal m11, qreal m12, qreal m13, qreal m21, qreal m22, qreal m23, qreal m31, qreal m32, qreal m33 = 1.0)

Создаёт матрицу с элементами m11, m12, m13, m21, m22, m23, m31, m32, m33.

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

QTransform::QTransform(qreal m11, qreal m12, qreal m21, qreal m22, qreal dx, qreal dy)

Создаёт матрицу с элементами m11, m12, m21, m22, dx и dy.

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

QTransform::QTransform(const QMatrix &matrix)

Создаёт матрицу, являющуюся копией заданной матрицы matrix. Обратите внимание, что элементы m13, m23, и m33 установлены в 0, 0 и 1 соответственно.

QTransform::QTransform(QTransform &&other)

Конструктор перемещения-копирования.

QTransform::QTransform(const QTransform &other)

Конструктор копирования.

qreal QTransform::m11() const

Возвращает коэффициент горизонтального масштабирования.

См. также scale() и Основные операции над матрицами.

qreal QTransform::m12() const

Возвращает коэффициент вертикального сдвига.

См. также shear() и Основные операции над матрицами.

qreal QTransform::m13() const

Возвращает коэффициент горизонтальной проекции.

См. также translate() и Основные операции над матрицами.

qreal QTransform::m21() const

Возвращает коэффициент горизонтального сдвига.

См. также shear() и Основные операции над матрицами.

qreal QTransform::m22() const

Возвращает коэффициент вертикального масштабирования.

См. также scale() и Основные операции над матрицами.

qreal QTransform::m23() const

Возвращает коэффициент вертикальной проекции.

См. также translate() и Основные операции над матрицами.

qreal QTransform::m31() const

Возвращает коэффициент горизонтального смещения.

См. также dx(), translate(), и Основные операции над матрицами.

qreal QTransform::m32() const

Возвращает коэффициент вертикального смещения.

См. также dy(), translate(), и Основные операции над матрицами.

qreal QTransform::m33() const

Возвращает коэффициент деления.

См. также translate() и Основные операции над матрицами.

QTransform QTransform::adjoint() const

Возвращает присоединённую матрицу.

qreal QTransform::determinant() const

Возвращает определитель матрицы.

qreal QTransform::dx() const

Возвращает коэффициент горизонтального смещения.

См. также m31(), translate(), и Основные операции над матрицами.

qreal QTransform::dy() const

Возвращает коэффициент вертикального смещения.

См. также translate() и Основные операции над матрицами.

[static] QTransform QTransform::fromScale(qreal sx, qreal sy)

Создаёт матрицу, соответствующую масштабированию по горизонтали на sx и по вертикали на sy. Это то же самое, что QTransform().scale(sx, sy), но немного быстрее.

Эта функция была добавлена в Qt 4.5.

[static] QTransform QTransform::fromTranslate(qreal dx, qreal dy)

Создаёт матрицу, соответствующую смещению на dx по оси x и dy по оси y. Это то же самое, что QTransform().translate(dx, dy), но немного быстрее.

Эта функция была добавлена в Qt 4.5.

QTransform QTransform::inverted(bool *invertible = Q_NULLPTR) const

Возвращает инвертированную копию этой матрицы.

Если матрица вырожденная (необратимая), возвращаемая матрица — единичная матрица. Если invertible допустимо (т.е. не 0), его значение устанавливается в true, если матрица обратима, иначе в false.

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

bool QTransform::isAffine() const

Возвращает true если матрица представляет аффинное преобразование, иначе возвращает false.

bool QTransform::isIdentity() const

Возвращает true если матрица — единичная матрица, иначе возвращает false.

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

bool QTransform::isInvertible() const

Возвращает true если матрица обратима, иначе возвращает false.

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

bool QTransform::isRotating() const

Возвращает true если матрица представляет какой-либо поворот, иначе возвращает false.

Примечание: Повороты на 180 и 360 градусов рассматриваются как масштабирование.

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

bool QTransform::isScaling() const

Возвращает true если матрица представляет масштабирование, иначе возвращает false.

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

bool QTransform::isTranslating() const

Возвращает true если матрица представляет смещение, иначе возвращает false.

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

void QTransform::map(qreal x, qreal y, qreal *tx, qreal *ty) const

Преобразует заданные координаты x и y в систему координат, определённую этой матрицей. Результаты записываются в *tx и *ty соответственно.

Координаты преобразуются по следующим формулам:

x' = m11*x + m21*y + dx
y' = m22*y + m12*x + dy
if (is not affine) {
    w' = m13*x + m23*y + m33
    x' /= w'
    y' /= w'
}

Точка (x, y) — исходная точка, а (x', y') — преобразованная точка.

См. также Основные операции с матрицей.

QPointF QTransform::map(const QPointF &p) const

Это перегруженный метод.

Создаёт и возвращает объект QPointF, представляющий копию заданной точки p, преобразованной в систему координат, определённую этой матрицей.

QLine QTransform::map(const QLine &l) const

Это перегруженный метод.

Создаёт и возвращает объект QLineF, представляющий копию заданной линии l, преобразованной в систему координат, определённую этой матрицей.

QLineF QTransform::map(const QLineF &line) const

Это перегруженный метод.

Создаёт и возвращает объект QLine, представляющий копию заданной линии line, преобразованной в систему координат, определённую этой матрицей. Обратите внимание, что преобразованные координаты округляются до ближайшего целого числа.

QPolygonF QTransform::map(const QPolygonF &polygon) const

Это перегруженный метод.

Создаёт и возвращает объект QPolygonF, представляющий копию заданного многоугольника polygon, преобразованного в систему координат, определённую этой матрицей.

QPolygon QTransform::map(const QPolygon &polygon) const

Это перегруженный метод.

Создаёт и возвращает объект QPolygon, представляющий копию заданного многоугольника polygon, преобразованного в систему координат, определённую этой матрицей. Обратите внимание, что преобразованные координаты округляются до ближайшего целого числа.

QRegion QTransform::map(const QRegion &region) const

Это перегруженный метод.

Создаёт и возвращает объект QRegion, представляющий копию заданной области region, преобразованной в систему координат, определённую этой матрицей.

Вызов этого метода может быть довольно затратным, если используются повороты или сдвиги.

QPainterPath QTransform::map(const QPainterPath &path) const

Это перегруженный метод.

Создаёт и возвращает объект QPainterPath, представляющий копию заданной траектории path, преобразованной в систему координат, определённую этой матрицей.

void QTransform::map(int x, int y, int *tx, int *ty) const

Это перегруженный метод.

Преобразует заданные координаты x и y в систему координат, определённую этой матрицей. Результаты записываются в *tx и *ty соответственно. Обратите внимание, что преобразованные координаты округляются до ближайшего целого числа.

QPoint QTransform::map(const QPoint &point) const

Это перегруженный метод.

Создаёт и возвращает объект QPoint, представляющий копию заданной точки point, преобразованной в систему координат, определённую этой матрицей. Обратите внимание, что преобразованные координаты округляются до ближайшего целого числа.

QRectF QTransform::mapRect(const QRectF &rectangle) const

Создаёт и возвращает объект QRectF, представляющий копию заданного прямоугольника rectangle, преобразованного в систему координат, определённую этой матрицей.

Координаты прямоугольника преобразуются по следующим формулам:

x' = m11*x + m21*y + dx
y' = m22*y + m12*x + dy
if (is not affine) {
    w' = m13*x + m23*y + m33
    x' /= w'
    y' /= w'
}

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

См. также mapToPolygon() и Основные операции с матрицей.

QRect QTransform::mapRect(const QRect &rectangle) const

Это перегруженный метод.

Создаёт и возвращает объект QRect, представляющий копию заданного прямоугольника rectangle, преобразованного в систему координат, определённую этой матрицей. Обратите внимание, что преобразованные координаты округляются до ближайшего целого числа.

QPolygon QTransform::mapToPolygon(const QRect &rectangle) const

Создаёт и возвращает представление заданного прямоугольника rectangle в виде многоугольника QPolygon, преобразованного в систему координат, определённую этой матрицей.

Координаты прямоугольника преобразуются по следующим формулам:

x' = m11*x + m21*y + dx
y' = m22*y + m12*x + dy
if (is not affine) {
    w' = m13*x + m23*y + m33
    x' /= w'
    y' /= w'
}

Многоугольники и прямоугольники ведут себя немного по-разному при преобразовании (из-за округления целых чисел), поэтому matrix.map(QPolygon(rectangle)) не всегда совпадает с matrix.mapToPolygon(rectangle).

См. также mapRect() и Основные операции с матрицей.

[static] bool QTransform::quadToQuad(const QPolygonF &one, const QPolygonF &two, QTransform &trans)

Создаёт матрицу преобразования trans, которая отображает четырёхугольник one на четырёхугольник two. Возвращает true если преобразование возможно; в противном случае возвращает false.

Это удобный метод, объединяющий методы quadToSquare() и squareToQuad(). Он позволяет преобразовать четырёхугольник в любой другой четырёхугольник.

См. также squareToQuad() и quadToSquare().

[static] bool QTransform::quadToSquare(const QPolygonF &quad, QTransform &trans)

Создаёт матрицу преобразования trans, которая отображает четырёхугольник quad на единичный квадрат. Возвращает true если преобразование построено или false, если такое преобразование не существует.

См. также squareToQuad() и quadToQuad().

void QTransform::reset()

Сбрасывает матрицу в единичную матрицу, т.е. все элементы устанавливаются в ноль, за исключением m11 и m22 (указывающие масштаб) и m33, которые устанавливаются в 1.

См. также QTransform(), isIdentity() и Основные операции с матрицей.

QTransform &QTransform::rotate(qreal angle, Qt::Axis axis = Qt::ZAxis)

Поворачивает систему координат против часовой стрелки на заданный угол angle вокруг указанной оси axis и возвращает ссылку на матрицу.

Обратите внимание, что если вы применяете QTransform к точке, определённой в координатах виджета, направление поворота будет по часовой стрелке, поскольку ось y направлена вниз.

Угол задаётся в градусах.

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

QTransform &QTransform::rotateRadians(qreal angle, Qt::Axis axis = Qt::ZAxis)

Поворачивает систему координат против часовой стрелки на заданный угол angle вокруг указанной оси axis и возвращает ссылку на матрицу.

Обратите внимание, что если вы применяете QTransform к точке, определённой в координатах виджета, направление поворота будет по часовой стрелке, поскольку ось y направлена вниз.

Угол задаётся в радианах.

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

QTransform &QTransform::scale(qreal sx, qreal sy)

Масштабирует систему координат по горизонтали на sx и по вертикали на sy, и возвращает ссылку на матрицу.

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

void QTransform::setMatrix(qreal m11, qreal m12, qreal m13, qreal m21, qreal m22, qreal m23, qreal m31, qreal m32, qreal m33)

Устанавливает элементы матрицы на указанные значения, m11, m12, m13, m21, m22, m23, m31, m32 и m33. Обратите внимание, что эта функция заменяет предыдущие значения. QTransform предоставляет удобные функции translate(), rotate(), scale() и shear() для изменения различных элементов матрицы на основе текущей системы координат.

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

QTransform &QTransform::shear(qreal sh, qreal sv)

Выполняет сдвиг системы координат на sh по горизонтали и sv по вертикали и возвращает ссылку на матрицу.

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

[static] bool QTransform::squareToQuad(const QPolygonF &quad, QTransform &trans)

Создаёт матрицу преобразования trans, отображающую единичный квадрат на четырёхугольник quad. Возвращает true, если преобразование построено, или false, если такое преобразование не существует.

См. также quadToSquare() и quadToQuad().

const QMatrix &QTransform::toAffine() const

Возвращает QTransform как аффинную матрицу.

Предупреждение: Если было задано перспективное преобразование, то преобразование вызовет потерю данных.

QTransform &QTransform::translate(qreal dx, qreal dy)

Перемещает систему координат на dx по оси x и dy по оси y и возвращает ссылку на матрицу.

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

QTransform QTransform::transposed() const

Возвращает транспонированную матрицу.

TransformationType QTransform::type() const

Возвращает тип преобразования этой матрицы.

Тип преобразования — это наибольшее значение перечисления, охватывающее все преобразования матрицы. Например, если матрица и масштабируется, и сдвигается, тип будет TxShear, так как TxShear имеет большее значение перечисления, чем TxScale.

Знание типа преобразования матрицы полезно для оптимизации: вы часто можете обрабатывать определённые типы эффективнее, чем общий случай.

QTransform::operator QVariant() const

Возвращает преобразование как QVariant.

bool QTransform::operator!=(const QTransform &matrix) const

Возвращает true, если эта матрица не равна заданной matrix, в противном случае возвращает false.

QTransform QTransform::operator*(const QTransform &matrix) const

Возвращает результат умножения этой матрицы на заданную matrix.

Обратите внимание, что умножение матриц не коммутативно, т.е. a*b != b*a.

QTransform &QTransform::operator*=(const QTransform &matrix)

Это перегруженная функция.

Возвращает результат умножения этой матрицы на заданную matrix.

QTransform &QTransform::operator*=(qreal scalar)

Это перегруженная функция.

Возвращает результат поэлементного умножения этой матрицы на заданный scalar.

QTransform &QTransform::operator+=(qreal scalar)

Это перегруженная функция.

Возвращает матрицу, полученную путём добавления заданного scalar к каждому элементу этой матрицы.

QTransform &QTransform::operator-=(qreal scalar)

Это перегруженная функция.

Возвращает матрицу, полученную путём вычитания заданного scalar из каждого элемента этой матрицы.

QTransform &QTransform::operator/=(qreal scalar)

Это перегруженная функция.

Возвращает результат поэлементного деления этой матрицы на заданный scalar.

QTransform &QTransform::operator=(QTransform &&other)

Оператор перемещающего присваивания.

QTransform &QTransform::operator=(const QTransform &matrix)

Присваивает значения заданной matrix этой матрице.

bool QTransform::operator==(const QTransform &matrix) const

Возвращает true, если эта матрица равна заданной matrix, в противном случае возвращает false.