/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \page coordsys.html

    \title The Coordinate System

    \brief Information about the coordinate system used by the paint

    system.

    \previouspage Drawing and Filling

    \contentspage The Paint System

    \nextpage Reading and Writing Image Files

    The coordinate system is controlled by the QPainter

    class. Together with the QPaintDevice and QPaintEngine classes,

    QPainter form the basis of Qt's painting system, Arthur. QPainter

    is used to perform drawing operations, QPaintDevice is an

    abstraction of a two-dimensional space that can be painted on

    using a QPainter, and QPaintEngine provides the interface that the

    painter uses to draw onto different types of devices.

    The QPaintDevice class is the base class of objects that can be

    painted: Its drawing capabilities are inherited by the QWidget,

    QPixmap, QPicture, QImage, and QPrinter classes. The default

    coordinate system of a paint device has its origin at the top-left

    corner. The \e x values increase to the right and the \e y values

    increase downwards. The default unit is one pixel on pixel-based

    devices and one point (1/72 of an inch) on printers.

    The mapping of the logical QPainter coordinates to the physical

    QPaintDevice coordinates are handled by QPainter's transformation

    matrix, viewport and "window". The logical and physical coordinate

    systems coincide by default. QPainter also supports coordinate

    transformations (e.g. rotation and scaling).

    \tableofcontents

    \section1 Rendering

    \section2 Logical Representation

    The size (width and height) of a graphics primitive always

    correspond to its mathematical model, ignoring the width of the

    pen it is rendered with:

    \table

    \row

    \o \inlineimage coordinatesystem-rect.png

    \o \inlineimage coordinatesystem-line.png

    \row

    \o QRect(1, 2, 6, 4)

    \o QLine(2, 7, 6, 1)

    \endtable

    \section2 Aliased Painting

    When drawing, the pixel rendering is controlled by the

    QPainter::Antialiasing render hint.

    The \l {QPainter::RenderHint}{RenderHint} enum is used to specify

    flags to QPainter that may or may not be respected by any given

    engine. The QPainter::Antialiasing value indicates that the engine

    should antialias edges of primitives if possible, i.e. smoothing

    the edges by using different color intensities.

    But by default the painter is \e aliased and other rules apply:

    When rendering with a one pixel wide pen the pixels will be

    rendered to the \e {right and below the mathematically defined

    points}. For example:

    \table

    \row

    \o \inlineimage coordinatesystem-rect-raster.png

    \o \inlineimage coordinatesystem-line-raster.png

    \row

    \o

    \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 0

    \o

    \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 1

    \endtable

    When rendering with a pen with an even number of pixels, the

    pixels will be rendered symetrically around the mathematical

    defined points, while rendering with a pen with an odd number of

    pixels, the spare pixel will be rendered to the right and below

    the mathematical point as in the one pixel case. See the QRectF

    diagrams below for concrete examples.

    \table

    \header

    \o {3,1} QRectF

    \row

    \o \inlineimage qrect-diagram-zero.png

    \o \inlineimage qrectf-diagram-one.png

    \row

    \o Logical representation

    \o One pixel wide pen

    \row

    \o \inlineimage qrectf-diagram-two.png

    \o \inlineimage qrectf-diagram-three.png

    \row

    \o Two pixel wide pen

    \o Three pixel wide pen

    \endtable

    Note that for historical reasons the return value of the

    QRect::right() and QRect::bottom() functions deviate from the true

    bottom-right corner of the rectangle.

    QRect's \l {QRect::right()}{right()} function returns \l

    {QRect::left()}{left()} + \l {QRect::width()}{width()} - 1 and the

    \l {QRect::bottom()}{bottom()} function returns \l

    {QRect::top()}{top()} + \l {QRect::height()}{height()} - 1.  The

    bottom-right green point in the diagrams shows the return

    coordinates of these functions.

    We recommend that you simply use QRectF instead: The QRectF class

    defines a rectangle in the plane using floating point coordinates

    for accuracy (QRect uses integer coordinates), and the

    QRectF::right() and QRectF::bottom() functions \e do return the

    true bottom-right corner.

    Alternatively, using QRect, apply \l {QRect::x()}{x()} + \l

    {QRect::width()}{width()} and \l {QRect::y()}{y()} + \l

    {QRect::height()}{height()} to find the bottom-right corner, and

    avoid the \l {QRect::right()}{right()} and \l

    {QRect::bottom()}{bottom()} functions.

    \section2 Anti-aliased Painting

    If you set QPainter's \l {QPainter::Antialiasing}{anti-aliasing}

    render hint, the pixels will be rendered symetrically on both

    sides of the mathematically defined points:

    \table

    \row

    \o \inlineimage coordinatesystem-rect-antialias.png

    \o \inlineimage coordinatesystem-line-antialias.png

    \row

    \o

    \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 2

    \o

    \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 3

    \endtable

    \section1 Transformations

    By default, the QPainter operates on the associated device's own

    coordinate system, but it also has complete support for affine

    coordinate transformations.

    You can scale the coordinate system by a given offset using the

    QPainter::scale() function, you can rotate it clockwise using the

    QPainter::rotate() function and you can translate it (i.e. adding

    a given offset to the points) using the QPainter::translate()

    function.

    \table

    \row

    \o \inlineimage qpainter-clock.png

    \o \inlineimage qpainter-rotation.png

    \o \inlineimage qpainter-scale.png

    \o \inlineimage qpainter-translation.png

    \row

    \o nop

    \o \l {QPainter::rotate()}{rotate()}

    \o \l {QPainter::scale()}{scale()}

    \o \l {QPainter::translate()}{translate()}

    \endtable

    You can also twist the coordinate system around the origin using

    the QPainter::shear() function. See the \l {demos/affine}{Affine

    Transformations} demo for a visualization of a sheared coordinate

    system. All the transformation operations operate on QPainter's

    transformation matrix that you can retrieve using the

    QPainter::worldTransform() function. A matrix transforms a point

    in the plane to another point.

    If you need the same transformations over and over, you can also

    use QTransform objects and the QPainter::worldTransform() and

    QPainter::setWorldTransform() functions. You can at any time save the

    QPainter's transformation matrix by calling the QPainter::save()

    function which saves the matrix on an internal stack. The

    QPainter::restore() function pops it back.

    One frequent need for the transformation matrix is when reusing

    the same drawing code on a variety of paint devices. Without

    transformations, the results are tightly bound to the resolution

    of the paint device. Printers have high resolution, e.g. 600 dots

    per inch, whereas screens often have between 72 and 100 dots per

    inch.

    \table 100%

    \header

    \o {2,1} Analog Clock Example

    \row

    \o \inlineimage coordinatesystem-analogclock.png

    \o

    The Analog Clock example shows how to draw the contents of a

    custom widget using QPainter's transformation matrix.

    Qt's example directory provides a complete walk-through of the

    example. Here, we will only review the example's \l

    {QWidget::paintEvent()}{paintEvent()} function to see how we can

    use the transformation matrix (i.e. QPainter's matrix functions)

    to draw the clock's face.

    We recommend compiling and running this example before you read

    any further. In particular, try resizing the window to different

    sizes.

    \row

    \o {2,1}

    \snippet examples/widgets/analogclock/analogclock.cpp 9

    First, we set up the painter. We translate the coordinate system

    so that point (0, 0) is in the widget's center, instead of being

    at the top-left corner. We also scale the system by \c side / 100,

    where \c side is either the widget's width or the height,

    whichever is shortest. We want the clock to be square, even if the

    device isn't.

    This will give us a 200 x 200 square area, with the origin (0, 0)

    in the center, that we can draw on. What we draw will show up in

    the largest possible square that will fit in the widget.

    See also the \l {Window-Viewport Conversion} section.

    \snippet examples/widgets/analogclock/analogclock.cpp 18

    We draw the clock's hour hand by rotating the coordinate system

    and calling QPainter::drawConvexPolygon(). Thank's to the

    rotation, it's drawn pointed in the right direction.

    The polygon is specified as an array of alternating \e x, \e y

    values, stored in the \c hourHand static variable (defined at the

    beginning of the function), which corresponds to the four points

    (2, 0), (0, 2), (-2, 0), and (0, -25).

    The calls to QPainter::save() and QPainter::restore() surrounding

    the code guarantees that the code that follows won't be disturbed

    by the transformations we've used.

    \snippet examples/widgets/analogclock/analogclock.cpp 24

    We do the same for the clock's minute hand, which is defined by

    the four points (1, 0), (0, 1), (-1, 0), and (0, -40). These

    coordinates specify a hand that is thinner and longer than the

    minute hand.

    \snippet examples/widgets/analogclock/analogclock.cpp 27

    Finally, we draw the clock face, which consists of twelve short

    lines at 30-degree intervals. At the end of that, the painter is

    rotated in a way which isn't very useful, but we're done with

    painting so that doesn't matter.

    \endtable

    For a demonstation of Qt's ability to perform affine

    transformations on painting operations, see the \l

    {demos/affine}{Affine Transformations} demo which allows the user

    to experiment with the transformation operations.  See also the \l

    {painting/transformations}{Transformations} example which shows

    how transformations influence the way that QPainter renders

    graphics primitives. In particular, it shows how the order of

    transformations affects the result.

    For more information about the transformation matrix, see the

    QTransform documentation.

    \section1 Window-Viewport Conversion

    When drawing with QPainter, we specify points using logical

    coordinates which then are converted into the physical coordinates

    of the paint device.

    The mapping of the logical coordinates to the physical coordinates

    are handled by QPainter's world transformation \l

    {QPainter::worldTransform()}{worldTransform()} (described in the \l

    Transformations section), and QPainter's \l

    {QPainter::viewport()}{viewport()} and \l

    {QPainter::window()}{window()}.  The viewport represents the

    physical coordinates specifying an arbitrary rectangle. The

    "window" describes the same rectangle in logical coordinates. By

    default the logical and physical coordinate systems coincide, and

    are equivalent to the paint device's rectangle.

    Using window-viewport conversion you can make the logical

    coordinate system fit your preferences. The mechanism can also be

    used to make the drawing code independent of the paint device. You

    can, for example, make the logical coordinates extend from (-50,

    -50) to (50, 50) with (0, 0) in the center by calling the

    QPainter::setWindow() function:

    \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 4

    Now, the logical coordinates (-50,-50) correspond to the paint

    device's physical coordinates (0, 0). Independent of the paint

    device, your painting code will always operate on the specified

    logical coordinates.

    By setting the "window" or viewport rectangle, you perform a

    linear transformation of the coordinates. Note that each corner of

    the "window" maps to the corresponding corner of the viewport, and

    vice versa. For that reason it normally is a good idea to let the

    viewport and "window" maintain the same aspect ratio to prevent

    deformation:

    \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 5

    If we make the logical coordinate system a square, we should also

    make the viewport a square using the QPainter::setViewport()

    function. In the example above we make it equivalent to the

    largest square that fit into the paint device's rectangle. By

    taking the paint device's size into consideration when setting the

    window or viewport, it is possible to keep the drawing code

    independent of the paint device.

    Note that the window-viewport conversion is only a linear

    transformation, i.e. it does not perform clipping. This means that

    if you paint outside the currently set "window", your painting is

    still transformed to the viewport using the same linear algebraic

    approach.

    \image coordinatesystem-transformations.png

    The viewport, "window" and transformation matrix determine how

    logical QPainter coordinates map to the paint device's physical

    coordinates. By default the world transformation matrix is the

    identity matrix, and the "window" and viewport settings are

    equivalent to the paint device's settings, i.e. the world,

    "window" and device coordinate systems are equivalent, but as we

    have seen, the systems can be manipulated using transformation

    operations and window-viewport conversion. The illustration above

    describes the process.

    \omit

    \section1 Related Classes

    Qt's paint system, Arthur, is primarily based on the QPainter,

    QPaintDevice, and QPaintEngine classes:

    \table

    \header \o Class \o Description

    \row

    \o QPainter

    \o

    The QPainter class performs low-level painting on widgets and

    other paint devices.  QPainter can operate on any object that

    inherits the QPaintDevice class, using the same code.

    \row

    \o QPaintDevice

    \o

    The QPaintDevice class is the base class of objects that can be

    painted. Qt provides several devices: QWidget, QImage, QPixmap,

    QPrinter and QPicture, and other devices can also be defined by

    subclassing QPaintDevice.

    \row

    \o QPaintEngine

    \o

    The QPaintEngine class provides an abstract definition of how

    QPainter draws to a given device on a given platform.  Qt 4

    provides several premade implementations of QPaintEngine for the

    different painter backends we support; it provides one paint

    engine for each supported window system and painting

    frameworkt. You normally don't need to use this class directly.

    \endtable

    The 2D transformations of the coordinate system are specified

    using the QTransform class:

    \table

    \header \o Class \o Description

    \row

    \o QTransform

    \o

    A 3 x 3 transformation matrix. Use QTransform to rotate, shear,

    scale, or translate the coordinate system.

    \endtable

    In addition Qt provides several graphics primitive classes. Some

    of these classes exist in two versions: an \c{int}-based version

    and a \c{qreal}-based version. For these, the \c qreal version's

    name is suffixed with an \c F.

    \table

    \header \o Class \o Description

    \row

    \o \l{QPoint}(\l{QPointF}{F})

    \o

    A single 2D point in the coordinate system. Most functions in Qt

    that deal with points can accept either a QPoint, a QPointF, two

    \c{int}s, or two \c{qreal}s.

    \row

    \o \l{QSize}(\l{QSizeF}{F})

    \o

    A single 2D vector. Internally, QPoint and QSize are the same, but

    a point is not the same as a size, so both classes exist.  Again,

    most functions accept either QSizeF, a QSize, two \c{int}s, or two

    \c{qreal}s.

    \row

    \o \l{QRect}(\l{QRectF}{F})

    \o

    A 2D rectangle. Most functions accept either a QRectF, a QRect,

    four \c{int}s, or four \c {qreal}s.

    \row

    \o \l{QLine}(\l{QLineF}{F})

    \o

    A 2D finite-length line, characterized by a start point and an end

    point.

    \row

    \o \l{QPolygon}(\l{QPolygonF}{F})

    \o

    A 2D polygon. A polygon is a vector of \c{QPoint(F)}s. If the

    first and last points are the same, the polygon is closed.

    \row

    \o QPainterPath

    \o

    A vectorial specification of a 2D shape. Painter paths are the

    ultimate painting primitive, in the sense that any shape

    (rectange, ellipse, spline) or combination of shapes can be

    expressed as a path. A path specifies both an outline and an area.

    \row

    \o QRegion

    \o

    An area in a paint device, expressed as a list of

    \l{QRect}s. In general, we recommend using the vectorial

    QPainterPath class instead of QRegion for specifying areas,

    because QPainterPath handles painter transformations much better.

    \endtable

    \endomit

    \sa {Analog Clock Example}, {Transformations Example}

*/