Класс QTransform

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

Этот класс был представлен в Qt 4.3.

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

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

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

Статические открытые члены

Связанные функции (Non-Members)

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

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

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(const QMatrix &matrix)

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

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

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

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

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

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

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

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

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

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

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 = 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') — преобразованная точка.

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

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

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

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

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 соответственно. Обратите внимание, что преобразованные координаты округляются до ближайшего целого числа.

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, отображенного в систему координат, определённую этой матрицей.

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

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.

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

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