Класс QTransform

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

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

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

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

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

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

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

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

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

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

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

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

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

QTransform предоставляет функцию isIdentity(), которая возвращает true , если матрица является единичной матрицей, и функцию isInvertible(), которая возвращает true , если матрица невырожденная (т. е. AB = BA = I). Функция inverted() возвращает инвертированную копию матрицы this, если она обратима (в противном случае возвращает единичную матрицу), а 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'
}

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

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

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.