September 96 - Game Controls for QuickDraw 3D
Game
Controls for QuickDraw 3D
Philip McBride
Whether
the user is navigating a starship or examining a model of the DNA helix, your
first-person 3D application must allow user control of the camera movements in
a scene. You must keep changing the camera's position and orientation in
response to what the user wants to see. Here you'll learn how to create those
camera movements and handle the user's directions. As part of the bargain,
you'll even get a refresher course in the associated geometry.
Letting the user control the movement of the camera (and thus the view) is
critical to first-person interactive 3D games and extremely useful in 3D
modeling systems. Through QuickDraw 3D's camera functions and supporting
mathematical functions, you can create game controls that direct the position
and orientation of a camera. In general, game controls take user input from any
input device and control the camera in ways that emulate movements of players,
such as people or aircraft. Game controls are useful for any type of 3D viewer
application, including 3D Internet browsers.
You'll start your career as a camera operator by learning about the basic moves
you can make with the camera. Then you'll create the various camera movements,
keep the camera movements smooth, and translate user inputs to move the camera.
The sample code (which is provided on this issue's CD) is a 3D viewer
application with camera movements activated by the keyboard or the mouse. In
all of the code, the geometry has been kept as simple as possible, but if you
need to brush up, you'll find a refresher course on calculating points and
vectors in 3D space.
For an overview of QuickDraw 3D, turn to "QuickDraw 3D: A New Dimension for
Macintosh Graphics" in develop Issue 22. That article discusses topics like
reading models, using a viewer, creating a camera, and managing documents that
have 3D information. To learn more about those and related topics, see the list
of recommended reading at the end of this article.
We'll be controlling camera movements based on first-person viewing, so the
camera will be our eyes. But before we move through a scene, let's take a look
at the kind of camera moves we plan to use.
The camera movements you would create in a 3D game for a person who is driving
a vehicle or walking on level ground are examples of ground movements. These
camera moves include moving forward, backward, sideways to the left, and
sideways to the right, plus turning to the left (pan or yaw left) and turning
to the right (pan or yaw right). Figure 1 illustrates these basic ground
movements.
Figure
1. Ground movements
You can also go airborne with a variety of camera movements. These fancier
camera moves are changes that might be typical of an aircraft. They include
ascending and descending (moving upward and downward), pitching (tilting) up
and down, and rolling (tilting) left and right. Figure 2 illustrates these
moves.
Figure
2. Air movements
Now to the fun part -- let's get that camera moving! What you must do to
achieve the previously described camera movements, both ground and air,
involves some geometry. If you're like most of us and have forgotten your 3D
geometry, see "3D Geometry 101" for a refresher course. The 3D geometry for our
camera moves is quite simple; it will stick to the kinds of calculations
illustrated in "3D Geometry 101."
First, let's take a look at our world. In Figure 3, we have an object in the
world coordinate system and a camera looking at the object. The camera has its
own coordinate system defined by its location (in world coordinates), up
vector, and point of interest.
Figure
3. Our world
If you're new to 3D programming (and perhaps a little rusty on your math),
here's a brief introduction to some of the 3D concepts you'll find in this
article's code.
A point is represented in 3D space by x, y, and z values in a coordinate
system. A vector is a magnitude (length) and direction; it's represented by an
initial point (usually the origin of the coordinate system) and a final point
{x, y, z}. Figure 4 illustrates a point and a vector in 3D space.
Figure
4. A point and a vector in 3D space
To add a vector and a point, you place the vector's initial point on that point
(keeping the vector's direction and magnitude). The new final point of the
moved vector is the point resulting from the addition. (See Figure 5.)
Figure 5. Adding a vector and a point
To subtract a vector from a point, you place the vector's final point on that
point (keeping the vector's direction and magnitude). The new initial point of
the moved vector is the result (Figure 6).
Figure
6. Subtracting a vector from a point
To create a vector between two points, you subtract the vectors defined by the
points (called position vectors). To do this, you first reverse (turn around)
the second vector and place its initial point on the final point of the first
vector. Then you make a new vector from the first vector's initial point to the
second vector's new final point. This new vector has the direction and
magnitude of the vector between the two points (Figure 7).
Figure 7. Creating a vector between two points
A translation of a point or a vector by Tx, Ty, and Tz values moves the point
or the vector by adding the T values to its own values (Figure 8).
Figure
8. Translating a point or a vector by T
In Figure 8, the translation value T is really from the translation part of a
transformation matrix. A transformation matrix is used to transform a point or
a vector by translation, rotation, and scaling. The transformation matrix you
use is 4 x 4 -- with the upper-left 3 x 3 portion acting as the rotation
matrix, the bottom-left 1 x 3 portion acting as the translation matrix, and the
top-left to bottom-right diagonal of the rotation matrix acting as the scaling
matrix. The following transformation matrix has elements labeled for
translation (T), rotation (R), and scaling (S). The fourth column is ignored
for simplicity.
When you apply a transformation to a point or a vector, you multiply by the
matrix, as in the following formula for our point {x, y, z} and a
transformation matrix:
[{Sx*R0,0*x + R1,0*y + R2,0*z + Tx},
{R0,1*x + Sy*R1,1*y + R2,1*z + Ty},
{R0,2*x + R1,2*y + Sz*R2,2*z + Tz}]
As you can see from this formula, if you only want the matrix to apply a
translation (the T's), the 3 x 3 rotation matrix will be all 0's except for the
scaling diagonal, which will be all 1's.
A rotation of a vector through an arbitrary angle about different axes will use
various R elements (the 3 x 3 rotation matrix of the transformation matrix),
depending on which axis you're rotating about. For rotations of
[[theta]] about the x axis, you get the matrix
For rotations about the z axis, you get
And for rotations about the y axis, you get the following matrix:
So to apply a rotation about an axis, you simply multiply the appropriate
rotation matrix by the vector. In Figure 9, the vector on the right is rotated
90deg. about the z axis in the {x, y} plane.
Figure
9. Rotating a vector about an axis
We'll be dealing with the vectors making up the camera's coordinate system for
many of our movement functions, so let's keep these in our application's
document structure. We'll keep the camera placement data there as well.
The document structure looks like this:
typedef struct _DocumentRecord {
...
TQ3Point3D cameraLocation;
TQ3Point3D pointOfInterest;
TQ3Vector3D xVector;
TQ3Vector3D yVector; // up vector
TQ3Vector3D zVector;
...
} DocumentRecord, *DocumentPtr;
The
first time we set up our camera, we'll set the values in our document to
correspond to the initial camera position. Then with each subsequent movement
of the camera, we'll update these fields. The initial camera data is
constructed by the code in Listing 1. In the function MyGetCameraData, we do
some of our geometric calculations to get the x and z vectors. We subtract the
two endpoints (the initial and final points) of the z vector to get that
vector. And we get the x vector by cross-multiplying the y and z vectors.
Listing 1. Initializing the camera data
void MyGetCameraData(DocumentPtr theDocument,
TQ3CameraObject theCamera)
{
TQ3CameraPlacement cameraPlacement;
// Get the camera data.
Q3Camera_GetPlacement(theCamera, &cameraPlacement);
// Set the document's camera data.
theDocument->cameraLocation = cameraPlacement.cameraLocation;
theDocument->pointOfInterest = cameraPlacement.pointOfInterest;
theDocument->yVector = cameraPlacement.upVector;
// Calculate the x and z vectors and assign them to the document.
Q3Point3D_Subtract(&theDocument->pointOfInterest,
&theDocument->cameraLocation, &theDocument->zVector);
Q3Vector3D_Cross(&theDocument->zVector,
&theDocument->yVector, &theDocument->xVector);
}
After
the fields in our document have been updated by some camera movement function,
we'll want to reset the camera to that new data with the function
MySetCameraData (Listing 2).
Listing 2. Setting the camera data after a move
void MySetCameraData(DocumentPtr theDocument,
TQ3CameraObject theCamera)
{
TQ3CameraPlacement cameraPlacement;
// Set the camera placement data.
cameraPlacement.cameraLocation = theDocument->cameraLocation;
cameraPlacement.pointOfInterest = theDocument->pointOfInterest;
cameraPlacement.upVector = theDocument->yVector;
// Set the camera data to the camera.
Q3Camera_SetPlacement(theCamera, &cameraPlacement);
}
With
that camera infrastructure, we're ready to move the camera around a bit. You
can find the code for all the moves on this issue's CD. Here you'll find only
the code for those movements that are unique. Code for those moves not shown
(but previously mentioned) is almost identical to one of the functions shown in
the listings.
To move the camera along the z axis either forward or backward, we call the
function MyMoveCameraZ (Listing 3). This function translates the camera
location and point of interest by the given delta. Note that the associated z
vector isn't changed.
Listing 3. Moving the camera along the z axis
void MyMoveCameraZ(DocumentPtr theDocument, float dZ)
{
TQ3ViewObject theView;
TQ3CameraObject theCamera;
TQ3Vector3D scaledVector;
TQ3Point3D newPoint;
// Get the view and the camera objects.
theView = theDocument->theView;
Q3View_GetCamera(theView, &theCamera);
// Scale the y vector to make it dY longer.
Q3Vector3D_Scale(&theDocument->yVector,
dY/Q3Vector3D_Length(&theDocument->yVector),
&scaledVector);
// Move the camera position and direction by the new vector.
Q3Point3D_Vector3D_Add(&theDocument->cameraLocation,
&scaledVector, &newPoint);
theDocument->cameraLocation = newPoint;
Q3Point3D_Vector3D_Add(&theDocument->pointOfInterest,
&scaledVector, &newPoint);
theDocument->pointOfInterest = newPoint;
// Set the updated camera data to the camera.
MySetCameraData(theDocument, theCamera);
// Update the view with the changed camera and dispose of the
// camera.
Q3View_SetCamera(theView, theCamera);
Q3Object_Dispose(theCamera);
}
To
move the camera along the x axis (right or left ) or along the y axis
(ascending or descending), you use code similar to Listing 3. The only
difference is that you base the translation on the change in x or y instead of
the change in z. In both cases, the associated vectors don't change.
Next, to rotate the camera right or left about the y axis, we call the
function MyRotateCameraY (Listing 4). This function first creates a
transformation matrix whose rotation matrix represents rotating about the y
axis. It then transforms both the z and x vectors by that rotation (thus
rotating those two vectors about the y axis). From the rotated z vector, we
obtain the point of interest by adding the camera location to the vector.
Listing 4. Rotating the camera about the y axis
void MyRotateCameraY(DocumentPtr theDocument, float dY)
{
TQ3ViewObject theView;
TQ3CameraObject theCamera;
TQ3Vector3D rotatedVector;
TQ3Matrix4x4 rotationMatrix;
// Get the view and the camera objects.
theView = theDocument->theView;
Q3View_GetCamera(theView, &theCamera);
// Create the rotation matrix for rotating about the y axis.
Q3Matrix4x4_SetRotateAboutAxis(&rotationMatrix,
&theDocument->cameraLocation, &theDocument->yVector, dY);
// Rotate the z vector about the y axis.
Q3Vector3D_Transform(&theDocument->zVector, &rotationMatrix,
&rotatedVector);
theDocument->zVector = rotatedVector;
// Rotate the x vector about the y axis.
Q3Vector3D_Transform(&theDocument->xVector, &rotationMatrix,
&rotatedVector);
theDocument->xVector = rotatedVector;
// Update the point of interest from the new z vector.
Q3Point3D_Vector3D_Add(&theDocument->cameraLocation,
&theDocument->zVector, &theDocument->pointOfInterest);
// Set the updated camera data to the camera.
MySetCameraData(theDocument, theCamera);
// Update the view with the changed camera and dispose of the
// camera.
Q3View_SetCamera(theView, theCamera);
Q3Object_Dispose(theCamera);
}
Rotating
the camera about the x axis (pitching up or down) or about the z axis (rolling
left or right) is similar to rotating it about the y axis. The main difference
is in how the rotation matrix is constructed (from the axis in question) and
which axes are rotated (the other two). The only other difference is that when
rotating the camera about the z axis, you don't have to update the point of
interest because it doesn't change.
To see what we've done to our world, we need a rendering loop, which you'll
find in the code on the CD. Since we don't do anything special in our rendering
loop, we'll skip the details. For an explanation of rendering loops, see the
article "QuickDraw 3D: A New Dimension for Macintosh Graphics" in develop Issue
22.
The real issue for us in viewing our camera movements is how smooth and fast
those moves appear. The factors that determine how smoothly and quickly the
moves work are the sizes (scales) of the deltas (the arguments to the movement
functions) and the speed of the machine (and therefore the subsequent speed of
the rendering loop). Adjusting for the speed of the machine is beyond the scope
of this article.
The sizes of the deltas determine the size of the jumps taken by each camera
movement. If the deltas are very small, the camera will move very slightly. And
if these movements are repeated, the camera will appear to move slowly over
time. If the deltas are large, the camera will appear to move fast.
If you move the camera too slowly, the movement will appear jumpy because the
user will see the delays in rendering time. If you move the camera too fast,
the movement will appear jumpy because, well, you're making the camera take big
jumps. To find just the right speed, you need to experiment with the sizes of
the deltas. The main thing to notice is that you should correlate the deltas to
the size of the model.
Listing 5 shows how you might set up the delta multipliers (called factors
here) that are used to help control movement. From the model's bounding box,
the MyInitDeltaFactors function determines the size of the largest dimension.
This model size is then used to generate the various factors for different
movement functions. Since accelerating the movements (say, by a control key) is
quite useful, this function sets that up too.
Listing 5. Creating delta factors based on the model's dimensions
void MyInitDeltaFactors(DocumentPtr theDocument)
{
TQ3BoundingBox viewBBox;
TQ3Vector3D diagonalVector;
float maxDimension;
// Get the bounding box and find the scene dimension.
MyGetBoundingBox(theDocument, &viewBBox);
Q3Point3D_Subtract(&viewBBox.max, &viewBBox.min,
&diagonalVector);
maxDimension = Q3Vector3D_Length(&diagonalVector);
// Now set the delta factors.
theDocument->xRotFactor = kXRotFactorBase * maxDimension;
theDocument->yRotFactor = kYRotFactorBase * maxDimension;
theDocument->zRotFactor = kZRotFactorBase * maxDimension;
theDocument->xMoveFactor = kXMoveFactorBase * maxDimension;
theDocument->yMoveFactor = kYMoveFactorBase * maxDimension;
theDocument->zMoveFactor = kZMoveFactorBase * maxDimension;
// Set up the control factor.
theDocument->controlFactor = kControlFactorBase * maxDimension;
}
Your
mileage may vary, so it's a good idea to take your camera out for a spin and
see what factors work for your application.
Now that you have the means of moving the camera this way and that, you need to
have something controlling those movements. Our application will use the
keyboard and the mouse.
To take input from the keyboard or the mouse, or both, we don't do anything
unusual. For the keyboard, we take the key-down events as they happen and
determine whether any other keys were held down at the time of the event (for
multiple key inputs). For the mouse, we just continually track it.
In both cases, the user can indicate movement along more than one dimension.
For example, if moving the mouse forward means "forward" and moving the mouse
left means a combination of "turn left" and "roll left," a mouse movement
that's both forward and to the left is a combination of three camera
movements.
Based on whether the user input is simple or complex, our code makes calls to
the appropriate camera movement functions. In the case of the mouse, the speed
of the mouse (the difference between the last position and the current
position) is also used to adjust the deltas for the camera movement. Listing 6
shows the code used for mouse tracking, but without the error handling and some
details of GWorlds and local coordinates (see this issue's CD for the full
source code). Here we've hard coded the meanings of the different mouse
movements and control keys for simplicity. Ideally, you would have this stored
in preference data that the user can set.
Listing 6. Tracking the mouse
void MyDoMouseMove(WindowPtr theWindow, EventRecord *theEvent)
{
DocumentPtr theDocument;
Point newMouse;
long dx, dy, oldX, oldY;
float xRot, yRot;
short usingControl = false;
// Get the document from the window.
theDocument = MyGetDocumentFromWindow(theWindow);
// Get the current mouse position.
GetMouse(&newMouse);
oldX = newMouse.h;
oldY = newMouse.v;
// If the control key is down, we're in depth mode.
if (theEvent->modifiers & controlKey)
usingControl = true;
// Loop, moving the camera while the mouse is down.
while (StillDown()) {
// Get the next mouse position.
GetMouse(&newMouse);
// Calculate the difference from the last mouse position.
dx = newMouse.h - oldX;
dy = oldY - newMouse.v;
// If there's some difference, move the camera.
if ((dx != 0) || (dy != 0)) {
// Calculate the rotation about the y axis (pan) and rotate.
yRot = ((float) dx * (kQPi / 180.0)) / theDocument->width;
MyRotateCameraY(theDocument,
-yRot * theDocument->yRotFactor);
// If the control key is down, move along the z axis;
// otherwise, rotate about the x axis.
if (usingControl) {
// Move the camera along the z axis
// (change in mouse's y).
MyMoveCameraZ(theDocument,
dy * theDocument->zMoveFactor);
} else {
// Calculate the rotation about the x axis (pitch) and
// rotate.
xRot = ((float) dy * (kQPi / 180.0)) /
theDocument->height;
MyRotateCameraX(theDocument,
xRot * theDocument->xRotFactor);
}
// Update the screen for each move.
MyUpdateScreen(theDocument);
}
// Set the current mouse position as the old mouse position for
// the next update.
oldX = newMouse.h;
oldY = newMouse.v;
}
}
The
code for handling keyboard input is even simpler. See the CD for that part of
the code.
Many other input devices are also applicable, especially 3D input devices. The
proper way to handle such input devices is through the QuickDraw 3D Pointing
Device Manager with its controllers and trackers. To use this approach, we
would need to define a tracker for our camera and assign it to the available
controllers. We would also change the camera movement functions so that they
took deltas of both position and orientation. See the book 3D Graphics
Programming With QuickDraw 3D and the Graphical Truffles column "Making the
Most of QuickDraw 3D" in develop Issue 24 for more on controllers and trackers.
(As of now, QuickDraw 3D doesn't have built-in controllers for the mouse and
the keyboard, so this code handles them directly.)
To make the geometry and the code for this article clearer, some efficiency
issues were ignored. But for most applications, the time spent in moving the
camera will be minimal when compared to the time spent rendering and displaying
each frame.
However, if the time used for the rendering-rastering phase is minimal and the
camera movements use a more significant percentage of the total time, there are
a number of solutions. The ultimate efficiency solution is to avoid making
any multiplications or divisions in the camera movements by using finite
differencing techniques when calculating the moves. This strategy involves
keeping more information about each intermediate change and making only the
incremental calculations necessary for the next move. This approach is similar
to operator reductions in compilers.
A number of applications can use game controls like those discussed here, not
just first-person 3D games. Another application that's a good candidate for the
kinds of game controls presented here would be a 3D Internet browser. You would
want similar 3D controls, but you would also want some controls for selecting
Web hot spots that would take you to another 3D Web site.
So now the next move is up to you.
- "QuickDraw 3D: A New Dimension for Macintosh Graphics" by Pablo Fernicola
and Nick Thompson, develop Issue 22.
- "Graphical Truffles: Making the Most of QuickDraw 3D" by Nick Thompson
and Pablo Fernicola, develop Issue 24.
- 3D Graphics Programming With QuickDraw 3D by Apple Computer, Inc.
(Addison-Wesley, 1995).
- Mathematical Elements for Computer Graphics, 2nd Edition, by David F.
Rogers and J. Alan Adams (McGraw-Hill, 1990).
- Tricks of the Mac Game Programming Gurus by Jamie McCornack and others
(Hayden Books, 1995).
PHILIP MCBRIDE (mcbride@apple.com) is currently adding QuickDraw 3D and
QuickTime VR to HyperCard 3.0. He used to spend time contemplating the meaning
of the universe until he figured it out. Now he can be seen wandering the halls
at Apple and mumbling something about needing more content. Lately, Philip has
been looking into investing in anteaters after learning that a full 20% of the
earth's biomass is made up of ants and termites. Just think about that
overcrowding the next time someone says we don't need to invest in space
travel.
Thanks to our technical reviewers Rick Evans, Richard Lawler, John Louch, Tim
Monroe, Nick Thompson, and Dan Venolia.
