|
|
              
QGLCamera ClassThe QGLCamera class defines the projection to apply to simulate a camera's position, orientation, and optics. More... #include <QGLCamera>Inherits: QObject. This class was introduced in Qt 4.8. Public Types
Properties
Public Functions
Public Slots
Signals
Additional Inherited MembersDetailed DescriptionThe QGLCamera class defines the projection to apply to simulate a camera's position, orientation, and optics. Modelview and projection transformationsA QGLCamera instance is applied to the scene in two phases: modelview transformation and projection transformation. During the modelview transformation, the eye(), center(), and upVector() are used to generate a 4x4 transformation matrix that reflects the viewer's current position and orientation. During the projection transformation, the projectionType(), nearPlane(), farPlane(), fieldOfView(), and viewSize() are used to define a viewing volume as a 4x4 transformation matrix. The modelview transformation matrix is returned by modelViewMatrix(). The projection transformation matrix is returned by projectionMatrix(). Positioning and orienting the viewThe viewer position and orientation are defined by eye(), center(), and upVector(). The location of the viewer in world co-ordinates is given by eye(), the viewer is looking at the object of interest located at center(), and the upVector() specifies the direction that should be considered "up" with respect to the viewer. The vector from the eye() to the center() is called the "view vector", and the cross-product of the view vector and upVector() is called the "side vector". The view vector specifies the direction the viewer is looking, and the side vector points off to the right of the viewer. It is recommended that the view vector and upVector() be at right angles to each other, but this is not required as long as the angle between them is close to 90 degrees. The most common use of view and up vectors that are not at right angles is to simulate a human eye at a specific height above the ground looking down at a lower object or up at a higher object. In this case, the the view vector will not be true horizontal, but the upVector() indicating the human's upright stance will be true vertical. Zooming the camera imageThere are two ways to zoom the image seen through the camera: either the camera eye() position can be moved closer to the object of interest, or the field of view of the camera lens can be changed to make it appear as though the object is moving closer. Changing the eye() position changes the lighting calculation in the scene because the viewer is in a different position, changing the angle of light reflection on the object's surface. The setFieldOfView() function can be used to simulate the effect of a camera lens. The smaller the fieldOfView(), the closer the object will appear. The lighting calculation will be the same as for the unzoomed scene. If fieldOfView() is zero, then a standard perspective frustum of viewSize() is used to define the viewing volume. The viewSize() can be adjusted with setViewSize() to zoom the view. A smaller viewSize() will make the the object appear closer. The fieldOfView() or viewSize() is applied as part of the projectionMatrix(). Rotating the viewer or object of interestRotating a viewer in 3D space is a very delicate process. It is very easy to construct the rotation incorrectly and end up in a "gimbal lock" state where further rotations are impossible in certain directions. To help alleviate this problem, QGLCamera uses a quaternion-based approach to generate rotations. A quaternion is a compact representation of a rotation in 3D space. Rotations can be combined through quaternion multiplication. More information on quaternions can be found in the documentation for QQuaternion. Before rotating the view, you should first decide the type of rotation you want to perform:
In the QGLCamera class, the first type of rotation is performed with rotateEye() and the second with rotateCenter(). Each of these functions take a quaternion argument that defines the type of rotation to perform. The tilt(), pan(), and roll() functions return values that can help with constructing the rotation quaternions to pass to rotateEye() and rotateCenter(). Tilt and pan are also known as "pitch" and "yaw" in flight dynamics. Three axes of rotation are used to compute the quaternions. The tilt() quaternion is computed with respect to the side vector, the pan() quaterion is computed with respect to the upVector(), and the roll() quaternion is computed with respect to the view vector. The following example tilts the direction the eye() is pointing by 5 degrees, and then pans by 45 degrees: camera.rotateEye(camera.tilt(5)); camera.rotateEye(camera.pan(45)); The next example performs the two rotations in a single fluid step (note that the rotation to be performed first is multiplied last): camera.rotateEye(camera.pan(45) * camera.tilt(5)); These two examples will not produce the same visual result, even though it looks like they might. In the first example, the upVector() is tilted before the pan() quaternion is computed. In the second example, the pan() quaternion is computed using the original upVector(). This difference in behavior is useful in different situations. Some applications may wish to perform all rotations relative to the original viewer orientation, and other applications may wish to perform rotations relative to the current viewer orientation. These application types correspond to the second and first examples above. Moving the viewer or object of interestThe simplest way to move the viewer or object of interest is to call setEye() or setCenter() respectively and supply a new position in world co-ordinates. However, this can lead to non-intuitive movements if the viewer orientation is not aligned with the world co-ordinate axes. For example, subtracting 3 from the eye() x co-ordinate will appear to move the eye left 3 units if the viewer orientation is aligned with the world co-ordinate axes. But it will not appear to move the eye left 3 units in any other orientation. The translation() function can be used to construct a translation vector that is aligned with the viewer's current orientation. Movement in the x direction will move along the side vector, movement in the y direction will move along upVector(), and movement in the z direction will move along the view vector. The translation() function is useful when implementing operations such as "step left", "jump up", and so on where the movement should be interpreted relative to the viewer's current orientation, not the world co-ordinate axes, In other words, the following two lines of code are not equivalent unless the view is oriented with the world co-ordinate axes: camera.translateEye(camera.translation(x, y, z)); camera.translateEye(QVector3D(x, y, z)); The following example translates the eye() position while keeping the object of interest at the original center(): camera.translateEye(camera.translation(x, y, z)); The following example translates the object of interest at center() while keeping the eye() position fixed: camera.translateCenter(camera.translation(x, y, z)); The following example translates both the eye() and the center() by the same amount, which will maintain the original view vector. QVector3D vector = camera.translation(x, y, z); camera.translateEye(vector); camera.translateCenter(vector); It is important that the translation vector for center() be computed before eye() is translated if both eye() and center() must move by the same amount. The following code translates center() in the viewer orientation after the eye() is translated: camera.translateEye(camera.translation(x, y, z)); camera.translateCenter(camera.translation(x, y, z)); Translating both eye() and center() by the same amount can be used to simulate sliding a viewer past a scene while always looking in the same direction (for example, filming a scene from a moving vehicle). An alternative is to fix the viewer and move the scene itself: the negation of the translation() vector can be applied to the scene's modelview transformation. Motion trackingViewing of 3D scenes can be enhanced if there is some way to track the motion of the viewer or the orientation of the display device. Applications can use setMotionAdjustment() to alter the position of the camera to account for the viewer's motion. This indicates the viewer's position relative to the center of the screen. The motionAdjustment() vector is used to determine by how much the camera position should be adjusted. The distance of the viewer from the screen is ignored. On handheld devices that use accelerometers to determine the orientation of the device, the down vector due to gravity can be adjusted to serve as a motion tracking vector. The output of motion tracking hardware can be very noisy, with minor fluctuations due to viewer twitch movements or environmental factors. The application is responsible for cleaning up the signal and removing these fluctuations before setMotionAdjustment() is called. Stereo projectionsQGLCamera can adjust the camera position for rendering separate left and right eye images by setting eyeSeparation() to a non-zero value. The eyeSeparation() is in world co-ordinates. Objects that are placed at center() will coincide in the left and right eye images, establishing the logical center of the stereo effect. Objects that are closer to the eye() will be rendered to appear closer in the stereo effect, and objects that are further away from eye() than center() will be rendered to appear further away. Perspective and Orthographic projections incorporate the eyeSeparation() into the modelViewMatrix() by altering the eye() position. See also QGLView and QGLPainter. Member Type Documentation
|
| Constant | Value | Description |
|---|---|---|
| QGLCamera::Perspective | 0 | Use a perspective view. |
| QGLCamera::Orthographic | 1 | Use an orthographic view. |
enum QGLCamera::RotateOrder
This enum defines the order to perform a tilt, pan, and roll of a QGLCamera eye or center.
| Constant | Value | Description |
|---|---|---|
| QGLCamera::TiltPanRoll | 0 | Tilt, then pan, then roll. |
| QGLCamera::TiltRollPan | 1 | Tilt, then roll, then pan. |
| QGLCamera::PanTiltRoll | 2 | Pan, then tilt, then roll. |
| QGLCamera::PanRollTilt | 3 | Pan, then roll, then tilt. |
| QGLCamera::RollTiltPan | 4 | Roll, then tilt, then pan. |
| QGLCamera::RollPanTilt | 5 | Roll, then pan, then tilt. |
Property Documentation
adjustForAspectRatio : bool
This property holds the adjustment state of the aspect ratio in the viewing volume.
By default, QGLCamera adjusts the viewing volume for the aspect ratio of the window so that pixels appear square without the application needing to adjust viewSize() manually.
If this property is false, then the aspect ratio adjustment is not performed.
Access functions:
| bool | adjustForAspectRatio() const |
| void | setAdjustForAspectRatio(bool value) |
Notifier signal:
| void | viewChanged() |
center : QVector3D
This property holds the center of the view visible from the viewer's position. The default value is (0, 0, 0).
Access functions:
| QVector3D | center() const |
| void | setCenter(const QVector3D & vertex) |
Notifier signal:
| void | viewChanged() |
See also translateCenter(), eye(), and upVector().
eye : QVector3D
This property holds the position of the viewer's eye. The default value is (0, 0, 10).
Access functions:
| QVector3D | eye() const |
| void | setEye(const QVector3D & vertex) |
Notifier signal:
| void | viewChanged() |
See also translateEye(), upVector(), center(), eyeSeparation(), and motionAdjustment().
eyeSeparation : qreal
This property holds the separation between the eyes when stereo viewing is in use, with eye() specifying the mid-point between the eyes. The default value is 0.
Access functions:
| qreal | eyeSeparation() const |
| void | setEyeSeparation(qreal value) |
Notifier signal:
| void | viewChanged() |
See also eye().
farPlane : qreal
This property holds the distance from the eye to the far clipping plane. The default value is 1000.
Access functions:
| qreal | farPlane() const |
| void | setFarPlane(qreal value) |
Notifier signal:
| void | projectionChanged() |
See also nearPlane().
fieldOfView : qreal
This property holds the field of view in degrees for a perspective projection.
The default value is zero, which indicates a standard perspective frustum view volume of viewSize() in size. If the value is not zero, then viewSize() is ignored.
This value is ignored if projectionType() is not Perspective.
Access functions:
| qreal | fieldOfView() const |
| void | setFieldOfView(qreal angle) |
Notifier signal:
| void | projectionChanged() |
See also viewSize().
minViewSize : QSizeF
This property holds the minimum size of the front of the projection viewing volume.
The minimum view size is used to clamp viewSize() when zooming the camera closer to an object to prevent it "passing through" the object and causing the scale factor to become infinite.
The default value is (0.0001, 0.0001).
Access functions:
| QSizeF | minViewSize() const |
| void | setMinViewSize(const QSizeF & size) |
Notifier signal:
| void | projectionChanged() |
See also projectionMatrix() and viewSize().
motionAdjustment : QVector3D
This property holds the adjustment vector to apply to the eye() for user motion.
This property is typically used to implement motion tracking. It is interpreted as a vector from the center of the screen to the current position of the viewer. The angle between the motion adjustment vector and the screen center is used to adjust the position of the eye() when modelViewMatrix() is called.
The default value is (0, 0, 1), which indicates a viewer directly in front of the center of the screen.
The units for the vector are unspecified. They could be meters, centimeters, or the force due to gravity in various directions from an accelerometer. The angle defined by the vector is used to perform the adjustment, not its magnitude.
The output of motion tracking hardware can be very noisy, with minor fluctuations due to viewer twitch movements or environmental factors. The application is responsible for cleaning up the signal and removing these fluctuations before altering this property.
Access functions:
| QVector3D | motionAdjustment() const |
| void | setMotionAdjustment(const QVector3D & vector) |
Notifier signal:
| void | viewChanged() |
See also eye() and modelViewMatrix().
nearPlane : qreal
This property holds the distance from the eye to the near clipping plane. The default value is 5.
Access functions:
| qreal | nearPlane() const |
| void | setNearPlane(qreal value) |
Notifier signal:
| void | projectionChanged() |
See also farPlane().
projectionType : ProjectionType
This property holds the projection type for this camera. The default is Perspective.
Access functions:
| QGLCamera::ProjectionType | projectionType() const |
| void | setProjectionType(QGLCamera::ProjectionType value) |
Notifier signal:
| void | projectionChanged() |
screenRotation : int
This property holds the screen rotation angle in degrees. The default value is 0. If this value is 90 or 270, then the view will be flipped width for height. The only supported values are 0, 90, 180, and 270. The screen is rotated around the positive z axis.
This setting is intended for simple screen rotations on handheld devices that can be held in either portrait or landscape orientations. The entire screen image is rotated so that it can be viewed in a different device orientation.
Use rotateEye() or rotateCenter() for more complex rotations that are not aligned with 0, 90, 180, or 270 degrees.
Access functions:
| int | screenRotation() const |
| void | setScreenRotation(int angle) |
Notifier signal:
| void | projectionChanged() |
upVector : QVector3D
This property holds the up vector for the viewer. The default value is (0, 1, 0).
Access functions:
| QVector3D | upVector() const |
| void | setUpVector(const QVector3D & vector) |
Notifier signal:
| void | viewChanged() |
viewSize : QSizeF
This property holds the size of the front of the projection viewing volume. The viewing volume is assumed to be centered on the origin.
The default value is (2, 2), which indicates a viewing volume front from (-1, -1) to (1, 1).
If the width or height of the viewing volume is negative, then the co-ordinates will be swapped. For example, a size of (2, -2) will flip the vertical axis upside down for a viewing volume from (-1, 1) to (1, -1).
The view size will be further adjusted by the window's aspect ratio when projectionMatrix() is called. For best results, the width and height of the view size should be the same to define an ideal square viewing volume, which is then extended to the final viewing volume width and height based on the window's aspect ratio.
Access functions:
| QSizeF | viewSize() const |
| void | setViewSize(const QSizeF & size) |
Notifier signal:
| void | projectionChanged() |
See also projectionMatrix() and minViewSize().
Member Function Documentation
QGLCamera::QGLCamera(QObject * parent = 0)
Constructs a QGLCamera with the default properties and attaches it to parent.
QGLCamera::~QGLCamera()
Destroys this QGLCamera object.
QGLCamera * QGLCamera::clone(QObject * parent = 0) const
Create a copy of this QGLCamera, parented onto the parent given, by default 0 (which results in no parenting).
The copy returned has exactly the same state as the original.
QVector3D QGLCamera::mapPoint(const QPoint & point, qreal aspectRatio, const QSize & viewportSize) const
Maps point from viewport co-ordinates to eye co-ordinates. The size of the viewport is given by viewportSize, and its aspect ratio by aspectRatio.
The returned vector will have its x and y components set to the position of the point on the near plane, and the z component set to -nearPlane().
This function is used for converting a mouse event's position into eye co-ordinates within the current camera view.
QMatrix4x4 QGLCamera::modelViewMatrix(QGL::Eye eye = QGL::NoEye) const
Returns the transformation to apply to the modelview matrix to present the scene as viewed from the eye position.
The eye parameter is used to adjust the camera's position horizontally by half of eyeSeparation() if eye is QGL::LeftEye or QGL::RightEye.
See also projectionMatrix().
QQuaternion QGLCamera::pan(qreal angle) const
Returns the quaternion corresponding to panning the view left or right by angle degrees. The returned quaternion can be applied to the eye() position with rotateEye() or to the center() position with rotateCenter().
See also tilt(), roll(), rotateEye(), and rotateCenter().
QMatrix4x4 QGLCamera::projectionMatrix(qreal aspectRatio) const
Returns the transformation matrix to apply to the projection matrix to present the scene as viewed from the camera position.
The aspectRatio specifies the aspect ratio of the window the camera view is being displayed in. An aspectRatio of 1 indicates that the window is square. An aspectRatio greater than 1 indicates that the window is wider than it is high. An aspectRatio less than 1 indicates that the window is higher than it is wide.
See also modelViewMatrix().
QQuaternion QGLCamera::roll(qreal angle) const
Returns the quaternion corresponding to rolling the view left or right by angle degrees. The returned quaternion can be applied to the eye() position with rotateEye() or to the center() position with rotateCenter().
See also tilt(), pan(), rotateEye(), and rotateCenter().
void QGLCamera::rotateCenter(const QQuaternion & q)
Rotates the position and orientation of the eye() around center() according to the quaternion q. The center() will remain in the same position, but the upVector() and eye() may be altered by the rotation.
See also rotateEye(), tilt(), pan(), and roll().
void QGLCamera::rotateEye(const QQuaternion & q)
Rotates the orientation of the eye() according to the quaternion q. The eye() will remain in the same position, but the upVector() and center() may be altered by the rotation.
See also rotateCenter(), tilt(), pan(), and roll().
QQuaternion QGLCamera::tilt(qreal angle) const
Returns the quaternion corresponding to tilting the view up or down by angle degrees. The returned quaternion can be applied to the eye() position with rotateEye() or to the center() position with rotateCenter().
See also pan(), roll(), rotateEye(), and rotateCenter().
void QGLCamera::tiltPanRollCenter(qreal tiltAngle, qreal panAngle, qreal rollAngle, QGLCamera::RotateOrder order = TiltPanRoll) [slot]
Tilts the center() up or down by tiltAngle degrees, pans the center() left or right by panAngle degrees, and rolls the center() left or right by rollAngle degrees, all in a single fluid movement. The order parameter indicates the order in which to perform the rotations.
This function is accessible to QML on the Camera item. It is provided as a convenience for navigation items that rotate the center in multiple directions at the same time based on mouse movements.
See also tiltPanRollEye().
void QGLCamera::tiltPanRollEye(qreal tiltAngle, qreal panAngle, qreal rollAngle, QGLCamera::RotateOrder order = TiltPanRoll) [slot]
Tilts the eye() up or down by tiltAngle degrees, pans the eye() left or right by panAngle degrees, and rolls the eye() left or right by rollAngle degrees, all in a single fluid movement. The order parameter indicates the order in which to perform the rotations.
This function is accessible to QML on the Camera item. It is provided as a convenience for navigation items that rotate the eye in multiple directions at the same time based on mouse movements.
See also tiltPanRollCenter().
void QGLCamera::translateCenter(qreal x, qreal y, qreal z) [slot]
Adjusts the center of the view by the components (x, y, z), where the components are interpreted relative to the viewer's current orientation. See translation() for more information.
This function is accessible to QML on the Camera item.
See also center(), setCenter(), and translateEye().
void QGLCamera::translateEye(qreal x, qreal y, qreal z) [slot]
Adjusts the position of the viewer's eye by the components (x, y, z), where the components are interpreted relative to the viewer's current orientation. See translation() for more information.
This function is accessible to QML on the Camera item.
See also eye(), setEye(), and translateCenter().
QVector3D QGLCamera::translation(qreal x, qreal y, qreal z) const
Returns a translation vector that can be used to adjust the eye() or center() by x units side-ways, y units up, and z units forwards.
This function is useful when implementing operations such as "step left", "jump up", and so on where the movement should be interpreted relative to the viewer's current orientation, not the world co-ordinate axes.
The following example moves the eye() 2 units to the right of the current eye position while keeping the same center() of interest:
camera.setEye(camera.eye() + camera.translation(2, 0, 0));
See also translateEye() and translateCenter().