Класс 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), выполнив ту же операцию над матрицей inverted().

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

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

enum 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)

Создаёт экземпляр QTransform по умолчанию.

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)

Создаёт матрицу, соответствующую масштабированию по оси X на sx и по оси Y на 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 = 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

Создаёт и возвращает многоугольник QPolygon, представляющий заданный прямоугольник 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'
}

Многоугольники и прямоугольники ведут себя немного по-разному при преобразовании (из-за округления до целых чисел), поэтому 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)

Масштабирует систему координат по оси x на sx и по оси y на 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

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

QTransform::TransformationType QTransform::type() const

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

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

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

QVariant 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.