Functions

( Boolean ) Q3ViewerAdjustCursor (
    TQ3ViewerObject theViewer,
    Point *pt
);

Discussion

Adjusts the mouse cursor if it's over the specified Viewer.

Call this function when the mouse moves, if it might be over the specified Viewer (or even if it's not). That gives the Viewer the opportunity to change the cursor as appropriate for the Viewer mode and cursor location.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

pt

Location of the cursor, in local (window) coordinates.

function result

True if the cursor was changed, false otherwise.

( OSErr ) Q3ViewerChangeBrightness (
    TQ3ViewerObject theViewer,
    float brightness
);

Discussion

Changes the intensity of lighting used on the model.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

brightness

Desired brightness (from 0 to 1?).

function result

Success or failure of the operation.

( OSErr ) Q3ViewerClear (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Clear editing command.

Call this function in response to the user selecting the standard Clear command when the viewer has the focus.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( Boolean ) Q3ViewerContinueTracking (
    TQ3ViewerObject theViewer,
    long x,
    long y
);

Discussion

Handles continued depression of the mouse.

If you're not using Q3ViewerEvent, then you'll should call this method after calling Q3ViewerMouseDown (and receiving a true result), whenever any event (such as a mouse movement) occurs as long as the mouse remains down.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

x

Horizontal global (screen) location of mouse cursor.

y

Vertical global (screen) location of mouse cursor.

function result

True if the Viewer handled the event, false otherwise.

( OSErr ) Q3ViewerCopy (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Copy editing command.

Call this function in response to the user selecting the standard Copy command when the viewer has the focus.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerCursorChanged (
    TQ3ViewerObject theViewer
);

Discussion

Notifies the Viewer that you have changed the cursor.

If you change the cursor (using SetCursor or similar), notify all active Viewers by calling this function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerCut (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Cut editing command.

Call this function in response to the user selecting the standard Cut command when the viewer has the focus.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerDispose (
    TQ3ViewerObject theViewer
);

Discussion

Disposes of a Viewer object.

Call this when you're done with the Viewer to ensure that Quesa has a chance to properly clean up after it.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer created with Q3ViewerNew.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerDraw (
    TQ3ViewerObject theViewer
);

Discussion

Forces the given Viewer to redraw itself.

You only need to call this function if the Viewer's flags or other visible features have changed. For example, to move or resize the Viewer, you would call Q3ViewerSetBounds followed by Q3ViewerDraw.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerDrawContent (
    TQ3ViewerObject theViewer
);

Discussion

Redraws the content area (i.e. the 3D view) of the given Viewer.

You should call this function if you directly modify the 3D model associated with the Viewer. In such a case, it's better to call this function than Q3ViewerDraw, which also redraws other user interface elements (such as control buttons).

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerDrawControlStrip (
    TQ3ViewerObject theViewer
);

Discussion

Redraws the user interface controls of the given Viewer.

Call this function when you want to redraw the controls, without re-rendering the 3D view.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( Boolean ) Q3ViewerEvent (
    TQ3ViewerObject theViewer,
    EventRecord *evt
);

Discussion

Handles a MacOS event.

This function gives the specified Viewer an opportunity to handle user interactiev via a classic (or Carbon) MacOS EventRecord. If the event was a Viewer-related event and successfully handled by the Viewer, this function returns true. Otherwise, it returns false, and you should proceed to handle the event yourself.

Note that this function implements a "closed-loop" event handling model; it should not be used in conjunction with the "open-loop" event functions (Q3ViewerMouseDown, Q3ViewerMouseUp, Q3ViewerContinueTracking, and Q3ViewerHandleKeyEvent).

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

evt

Address of event record to process.

function result

True if event was handled, false if not handled.

( OSErr ) Q3ViewerGetBackgroundColor (
    TQ3ViewerObject theViewer,
    TQ3ColorARGB *color
);

Discussion

Returns the background color of the 3D view.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

color

Pointer to TQ3ColorARGB to receive background color.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerGetBounds (
    TQ3ViewerObject theViewer,
    Rect *bounds
);

Discussion

Gets the current bounding rectangle of the Viewer pane.

The bounding rectangle determines where the Viewer draws itself within its window. The bounds are in window coordinates, with (0,0) being the top-left corner of the window.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

bounds

Address of Rect to receive Viewer bounds.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerGetButtonRect (
    TQ3ViewerObject theViewer,
    unsigned long button,
    Rect *rect
);

Discussion

Gets the rectangle that encloses a Viewer control button.

Specify the button of interest with one of the following constants:

kQ3ViewerButtonCamera kQ3ViewerButtonTruck kQ3ViewerButtonOrbit kQ3ViewerButtonZoom kQ3ViewerButtonDolly kQ3ViewerButtonReset kQ3ViewerButtonOptions

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

button

Which button to get (e.g., kQ3ViewerButtonCamera).

rect

Address of a rectangle to stuff with button bounds.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerGetCameraCount (
    TQ3ViewerObject theViewer,
    unsigned long *cnt
);

Discussion

Returns how many cameras are supplied by the Viewer's view hints.

Model files may contain view hints which provide things such as "good" camera positions. This function will report how many such cameras are suggested. If there are no view hints associated with the Viewer, then this function returns 0.

See also Q3ViewerSetCameraByNumber.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

cnt

Address of integer to receive the camera count.

function result

Success or failure of the operation.

( unsigned long ) Q3ViewerGetCurrentButton (
    TQ3ViewerObject theViewer
);

Discussion

Gets the currently selected mode button of the given Viewer.

A Viewer object always has a "mode" which determines how mouse drags in the content area are interpreted. Modes are selected by clicking on one of the mode buttons; this function tells you which one is currently active. The result will be one of the following:

kQ3ViewerButtonTruck kQ3ViewerButtonOrbit kQ3ViewerButtonZoom kQ3ViewerButtonDolly

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Active mode button.

( OSErr ) Q3ViewerGetDimension (
    TQ3ViewerObject theViewer,
    unsigned long *width,
    unsigned long *height
);

Discussion

Get the dimensions of model space in a Viewer's view hints object.

If the specified Viewer has no view hints, then this function just returns the actual width and height of the viewer pane.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

width

Address of an integer to receive the hinted width.

height

Address of an integer to receive the hinted height.

function result

Success or failure of the operation.

( unsigned long ) Q3ViewerGetFlags (
    TQ3ViewerObject theViewer
);

Discussion

Gets the Viewer feature flags currently in effect.

See Q3ViewerSetFlags for a listing of the possible flags.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Current feature flags.

( TQ3GroupObject ) Q3ViewerGetGroup (
    TQ3ViewerObject theViewer
);

Discussion

Returns a reference to the 3D model data being used by the Viewer.

The reference count of the TQ3GroupObject returned is incremented by this call. Therefore, you should call Q3Object_Dispose on this value when you're with it.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Group containing 3D model data.

( OSErr ) Q3ViewerGetMinimumDimension (
    TQ3ViewerObject theViewer,
    unsigned long *width,
    unsigned long *height
);

Discussion

Gets the minimum allowable size of the viewer pane.

The returned size will take into account the currently displayed buttons in the controller strip. If you allow the viewer pane (or its window) to be resized, you should not allow it to be resized smaller than the values returned by this function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

width

Address of an integer to receive the minimum viewer width.

height

Address of an integer to receive the minimum viewer height.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerGetPhongShading (
    TQ3ViewerObject theViewer,
    TQ3Boolean *phong
);

Discussion

Reports whether the Viewer is set to use phong shading.

Phong shading is generally slower but produces a more realistic effect, particularly where highlights are concerned.

Not all renderers support phong shading. A value of true reported by this function indicates only that the phong shading option is turned on; not whether the renderer is actually rendering any differently because of it.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

phong

Address of boolean to receive phone shading option.

function result

Success or failure of the operation.

( PicHandle ) Q3ViewerGetPict (
    TQ3ViewerObject theViewer
);

Discussion

Gets a 2D image of the Viewer's rendering in 'PICT' format.

This function builds a MacOS Picture containing the current rendering in the given Viewer. The caller is responsible for releasing the picture memory via DisposeHandle.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Handle to newly created picture.

( CGrafPtr ) Q3ViewerGetPort (
    TQ3ViewerObject theViewer
);

Discussion

Gets the graphics port into which the specified Viewer draws.

The returned port may be associated with a window or an offscreen graphics world; or it may be NULL, indicating that the Viewer is not associated with any port.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Associated color graphics port.

( OSErr ) Q3ViewerGetReleaseVersion (
    unsigned long *releaseRevision
);

Discussion

Returns the version number of the Quesa viewer, in 'vers' format.

The four bytes contain 1) the major revision level, 2) the minor revision, 3) the development stage, and 4) the prerelease revision level, respectively. The three revision levels are each represented in binary coded decimal. The development stage can be development (0x20), alpha (0x40), beta (0x60) or release (0x80).

For example, if the revision is 1.61a23 (= 1.6.1a23), returns 0x01614023. For more information, see the description of the 'vers' resource in the book Inside Macintosh: Macintosh Toolbox Essentials.

See also the Q3ViewerGetVersion function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

releaseRevision

Address of integer to receive version data.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerGetRemoveBackfaces (
    TQ3ViewerObject theViewer,
    TQ3Boolean *remove
);

Discussion

Reports whether the Viewer is currently removing back-facing polygons.

Use this function to discover how the Viewer handles polygons which face away from the camera. If it stores true in the remove parameter, such polygons are not being drawn. If it stores false, all polygons are being drawn, even when they face away from the camera.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

remove

Address of boolean to receive backfacing option.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerGetRendererType (
    TQ3ViewerObject theViewer,
    TQ3ObjectType *rendererType
);

Discussion

Gets the renderer type currently used by the Viewer.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

rendererType

Address to stuff with current renderer type.

function result

Success or failure of the operation.

( unsigned long ) Q3ViewerGetState (
    TQ3ViewerObject theViewer
);

Discussion

Returns a set of status bits indicating the viewer state.

The bits returned will be some combination of the following: kQ3ViewerEmpty: no image is currently displayed kQ3ViewerHasModel: an image of a 3D model is currently displayed kQ3ViewerHasUndo: the Viewer is able to undo a recent action

You might use these flags to enable the appropriate items of the Edit menu, for example.

See also the Q3ViewerGetUndoString function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

The current viewer state.

( Boolean ) Q3ViewerGetUndoString (
    TQ3ViewerObject theViewer,
    char *str,
    unsigned long *cnt
);

Discussion

Gets text for the current Undo operation.

This function stores the name of the current Undoable operation in the user-supplied character buffer. The text should be localized to the user's preferred language (but probably is not, in Quesa 1.6 at least). Note that this text does not contain the "Undo" word itself, but only the name of the operation. So if you want to use this to set the text of a menu item, you'll need to combine it with "Undo " yourself.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

str

Pointer to a character buffer.

cnt

On entry, the buffer size; on exit, the text length.

function result

True if there is an Undoable operation; false otherwise.

( OSErr ) Q3ViewerGetVersion (
    unsigned long *majorRevision,
    unsigned long *minorRevision
);

Discussion

Returns the major and minor version number of the Quesa viewer.

For example, if the revision is 1.6a23 (= 1.6.0a23), returns 1 as the major revision level and 6 as the minor revision level: The final 0 in the minor revision level is omitted. If the revision is 1.61a23 (= 1.6.1a23), returns 1 as the major revision level and 61 as the minor revision level.

See also the Q3ViewerGetReleaseVersion function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

majorRevision

Address of integer to receive major version number.

minorRevision

Address of integer to receive major version number.

function result

Success or failure of the operation.

( TQ3ViewObject ) Q3ViewerGetView (
    TQ3ViewerObject theViewer
);

Discussion

Returns the view object associated with the given Viewer.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

View object associated with this Viewer.

( Boolean ) Q3ViewerHandleKeyEvent (
    TQ3ViewerObject theViewer,
    EventRecord *evt
);

Discussion

Handles a key event.

If you're not using Q3ViewerEvent, then you'll need to handle a key event that occurs while the Viewer has the focus by calling this method.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

evt

Address of MacOS event record describing a key event.

function result

True if the Viewer handled the event, false otherwise.

( Boolean ) Q3ViewerMouseDown (
    TQ3ViewerObject theViewer,
    long x,
    long y
);

Discussion

Handles a mouse-down event.

If you're not using Q3ViewerEvent, then you'll need to handle a mouse-down event by calling this function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

x

Horizontal global (screen) location of mouse down.

y

Vertical global (screen) location of mouse down.

function result

True if the Viewer handled the event, false otherwise.

( Boolean ) Q3ViewerMouseUp (
    TQ3ViewerObject theViewer,
    long x,
    long y
);

Discussion

Handles a mouse-up event.

If you're not using Q3ViewerEvent, then you'll need to handle a mouse-up event by calling this function. But you only need to do so if Q3ViewerMouseDown returned true.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

x

Horizontal global (screen) location of mouse up.

y

Vertical global (screen) location of mouse up.

function result

True if the Viewer handled the event, false otherwise.

( TQ3ViewerObject ) Q3ViewerNew (
    CGrafPtr port,
    Rect *rect,
    unsigned long flags
);

Discussion

Creates a new Viewer. Note that despite the type nomenclature (TQ3ViewerObject), this is not a Quesa object, and can't be used with Q3Object functions such as Q3Object_Dispose.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

port

MacOS port to which the Viewer should be attached.

rect

Address of a bounding rectangle, in port coordinates.

flags

Any combination of Viewer flags (consider using kQ3ViewerDefault).

function result

Newly created Viewer, or NULL if Viewer could not be created.

( OSErr ) Q3ViewerPaste (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Paste editing command.

Call this function in response to the user selecting the standard Paste command when the viewer has the focus.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerRestoreView (
    TQ3ViewerObject theViewer
);

Discussion

Resets the viewer camera according to the settings in the associated view hints object. If there are no view hints, resets the camera to a standard default state.

This has the same effect as clicking the reset button in the viewer controls.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetBackgroundColor (
    TQ3ViewerObject theViewer,
    TQ3ColorARGB *color
);

Discussion

Sets the background color of the 3D view.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

color

Color to use as background for the 3D rendering.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetBounds (
    TQ3ViewerObject theViewer,
    Rect *bounds
);

Discussion

Sets the bounding rectangle for the Viewer pane.

Call this function to change where the Viewer draws itself within its window. The bounds are in window coordinates, with (0,0) being the top-left corner of the window.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

bounds

Address of a Rect containing new desired bounds

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetCameraByNumber (
    TQ3ViewerObject theViewer,
    unsigned long cameraNum
);

Discussion

Sets the view to a camera in the Viewer's view hints.

Model files may contain view hints which provide things such as "good" camera positions. This function selects one of those cameras. The camera number supplied is 1-based, and the value must be less than or equal to the result of Q3ViewerGetCameraCount.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

cameraNum

1-based index of camera to select.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetCameraByView (
    TQ3ViewerObject theViewer,
    TQ3ViewerCameraView viewType
);

Discussion

Sets the camera to one of the predefined views.

Possible values for viewType are: kQ3ViewerCameraRestore -- reset to initial position kQ3ViewerCameraFit -- fit entire model in the view kQ3ViewerCameraFront -- look at the front of the model kQ3ViewerCameraBack -- look at the back of the model kQ3ViewerCameraLeft -- look at the left side of the model kQ3ViewerCameraRight -- look at the right side of the model kQ3ViewerCameraTop -- look down at the top of the model kQ3ViewerCameraBottom -- look up at the bottom of the model

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

viewType

A constant selecting one of the predefined views.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetCurrentButton (
    TQ3ViewerObject theViewer,
    unsigned long button
);

Discussion

Sets the currently selected mode button of the given Viewer.

A Viewer object always has a "mode" which determines how mouse drags in the content area are interpreted. Modes are selected by clicking on one of the mode buttons; this function has exactly the same effect as a click on the specified button. The button parameter should be one of the following:

kQ3ViewerButtonTruck kQ3ViewerButtonOrbit kQ3ViewerButtonZoom kQ3ViewerButtonDolly

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

button

Constant indicating a mode button.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetDimension (
    TQ3ViewerObject theViewer,
    unsigned long width,
    unsigned long height
);

Discussion

Sets the dimensions of model space in a Viewer's view hints object.

This might be useful if you were then going to write a 3DMF file of the Viewer data; presumably it could store this hint in that file.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

width

Desired width of the viewer pane.

height

Desired height of the viewer pane.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetDrawingCallbackMethod (
    TQ3ViewerObject theViewer,
    TQ3ViewerDrawingCallbackMethod callbackMethod,
    const void *data
);

Discussion

Sets a callback function to be called after any drawing.

This function is invoked after the Viewer draws any part of itself. You can use it to do any further processing you might need to do. For example, if the Viewer is associated with an offscreen graphics world, you might use this callback to update the screen.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

callbackMethod

Pointer to a drawing callback routine.

data

Arbitrary pointer passed to your callback routine.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetFlags (
    TQ3ViewerObject theViewer,
    unsigned long flags
);

Discussion

Sets the Viewer feature flags. Flags are as follows:

kQ3ViewerShowBadge: If set, a badge is displayed when the controller strip is not visible. kQ3ViewerActive: Indicates that the viewer is active (rather than deactivated). kQ3ViewerControllerVisible: If set, the controller strip is visible. kQ3ViewerDrawFrame: If set, a one-pixel frame is drawn within the viewer pane. kQ3ViewerDraggingOff: If set, drag and drop is turned off (both dragging in and dragging out). kQ3ViewerButtonCamera: If set, the camera viewpoint control is displayed in the controller strip. kQ3ViewerButtonTruck: If set, the distance mode button is displayed in the controller strip. kQ3ViewerButtonOrbit: If set, the rotate mode button is displayed in the controller strip. kQ3ViewerButtonZoom: If set, the zoom mode button is displayed in the controller strip. kQ3ViewerButtonDolly: If set, the move (translate) mode button is displayed in the controller strip. kQ3ViewerButtonReset: If set, the reset button is displayed in the controller strip. kQ3ViewerOutputTextMode: If set, the Q3ViewerWriteFile function writes 3DMF data in text mode rather than binary. (Note: not currently supported!) kQ3ViewerDragMode: If set, the viewer is in drag and drop mode, causing it to respond only to drag and drop interaction. kQ3ViewerDrawGrowBox: If set, a grow (resize) box is drawn in the lower-right corner of the viewer pane. kQ3ViewerDrawDragBorder: If set, a drag border is drawn around the border of the rendering pane. The user can then initiate a drag by grabbing this border with the mouse. kQ3ViewerDraggingInOff: If set, dragging into the viewer pane is disabled. kQ3ViewerDraggingOutOff: If set, dragging out of the viewer pane is disabled. kQ3ViewerButtonOptions: If set, the options button is displayed in the controller strip. kQ3ViewerPaneGrowBox: ? kQ3ViewerDefault: Represents the default Viewer configuration.

Changes to the Viewer's flags will not be visible until the Viewer is redrawn (e.g., by calling Q3ViewerDraw).

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

flags

Desired combination of feature flags.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetPaneResizeNotifyCallback (
    TQ3ViewerObject theViewer,
    TQ3ViewerPaneResizeNotifyCallbackMethod paneResizeNotifyCallbackMethod,
    const void *data
);

Discussion

Sets a callback function to be called when the Viewer is resized.

This function is invoked when the Viewer is resized. You can use it to do any further processing that might be needed.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

paneResizeNotifyCallbackMethod

Pointer to a pane resize callback procedure.

data

Arbitrary pointer passed to your callback routine.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetPhongShading (
    TQ3ViewerObject theViewer,
    TQ3Boolean phong
);

Discussion

Tells the Viewer whether to render with phong shading.

Phong shading is generally slower but produces a more realistic effect, particularly where highlights are concerned. (Not all renderers support phong shading.)

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

phong

Whether phong shading is desired.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetPort (
    TQ3ViewerObject theViewer,
    CGrafPtr port
);

Discussion

Set the graphics port into which the Viewer should draw.

The given port may be either associated with a window, or it may be an offscreen graphics world. Note that under classic MacOS, a Window and its port are basically the same thing, but this is not true under Carbon. Take care to pass in an actual CGrafPtr, not a WindowRef (use GetWindowPort to get a window's port). You may also pass in NULL to indicate that no port should be associated with this Viewer object.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

port

Color graphics port to be used by this Viewer.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetRemoveBackfaces (
    TQ3ViewerObject theViewer,
    TQ3Boolean remove
);

Discussion

Tells the Viewer whether to draw back-facing polygons.

Use this function to change how the Viewer handles polygons which face away from the camera. If you pass true for the remove parameter, such polygons will not be drawn. If you pass false, all polygons will be drawn, even when they face away from the camera.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

remove

Whether backfaces should be removed.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetRendererType (
    TQ3ViewerObject theViewer,
    TQ3ObjectType rendererType
);

Discussion

Sets the renderer type used by the Viewer.

Calling this function is equivalent to selecting one of the renderers from the pop-up menu on the Options control button. The object type must be associated with one of the installed renderers.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

rendererType

Type of renderer to use.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerSetWindowResizeCallback (
    TQ3ViewerObject theViewer,
    TQ3ViewerWindowResizeCallbackMethod windowResizeCallbackMethod,
    const void *data
);

Discussion

Sets a callback function to be called when window containing the Viewer is resized.

This function is invoked when the Viewer is resized. You can use it to do any further processing that might be needed. For example, you might resize or move your Viewer pane to fit the new window bounds.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

windowResizeCallbackMethod

Pointer to a window resize callback procedure.

data

Arbitrary pointer passed to your callback routine.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerUndo (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Undo editing command.

Call this function in response to the user selecting the standard Undo command when the viewer has the focus.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( OSErr ) Q3ViewerUseData (
    TQ3ViewerObject theViewer,
    void *data,
    long size
);

Discussion

Loads 3D model data in memory into the Viewer.

The given data buffer is copied by the Viewer; the caller is responsible for disposing of it and may do so immediately after this call.

See also: Q3ViewerUseFile, Q3ViewerUseGroup.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

data

Pointer to a buffer containing model data.

size

Length of the data buffer (in bytes).

function result

Success or failure of the operation.

( OSErr ) Q3ViewerUseFile (
    TQ3ViewerObject theViewer,
    long refNum
);

Discussion

Load data from a 3D model file into the Viewer.

See also: Q3ViewerUseData, Q3ViewerUseGroup.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

refNum

MacOS file reference number (e.g., obtained from FSOpen).

function result

Success or failure of the operation.

( OSErr ) Q3ViewerUseGroup (
    TQ3ViewerObject theViewer,
    TQ3GroupObject group
);

Discussion

Loads a model data in a TQ3Group into the specified Viewer.

See also: Q3ViewerUseFile, Q3ViewerUseData.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

group

Model data to load.

function result

Success or failure of the operation.

( unsigned long ) Q3ViewerWriteData (
    TQ3ViewerObject theViewer,
    Handle data
);

Discussion

Copies the 3D model data contained by the Viewer into a MacOS Handle.

The data handle must already exist and be of a size large enough to hold the model data. Unfortunately, you have no good way to know how large it needs to be, except by trial and error (or by remembering from when the data was loaded in the first place).

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

data

Handle to stuff with viewer data.

function result

Number of bytes actually written, or 0 to indicate failure.

( OSErr ) Q3ViewerWriteFile (
    TQ3ViewerObject theViewer,
    long refNum
);

Discussion

Write the 3D model data contained by the Viewer out to a file.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

refNum

MacOS file reference number (e.g., obtained from FSOpen).

function result

Success or failure of the operation.

( TQ3Boolean ) Q3Viewer_AdjustCursor (
    TQ3ViewerObject theViewer,
    TQ3Uns32 hPos,
    TQ3Uns32 vPos
);

Discussion

Adjusts the mouse cursor for a viewer.

Should be called when the mouse moves into the viewer area, but may be called for any coordinate. Allows the Viewer to change the cursor as appropriate for the Viewer mode and cursor location.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

hPos

Horizontal location of the cursor.

vPos

Vertical location of the cursor.

function result

Returns as the cursor was changed by the viewer.

( TQ3Status ) Q3Viewer_CursorChanged (
    TQ3ViewerObject theViewer
);

Discussion

Notifies the Viewer that you have changed the cursor.

If you change the cursor within your application, notify the active viewer using this routine.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_Dispose (
    TQ3ViewerObject theViewer
);

Discussion

Disposes of a Viewer object.

Applications which rely on Q3Viewer_New to automatically initialise Quesa should use Q3Viewer_Dispose to destroy viewer objects. This will allow Quesa to be shut down when the last viewer object is destroyed.

Applications which initialise Quesa before creating a viewer object can dispose of their viewers with either Q3Viewer_Dispose or Q3Object_Dispose. Quesa will not be shut down until the application makes its final call to Q3Exit.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer created with Q3Viewer_New.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_Draw (
    TQ3ViewerObject theViewer
);

Discussion

Forces the viewer to redraw itself.

Should be called after the changing the Viewer's flags or visible features. For example, to move or resize a Viewer, call Q3Viewer_SetBounds followed by Q3Viewer_Draw.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_DrawContent (
    TQ3ViewerObject theViewer
);

Discussion

Redraws the content area (i.e. the 3D view) of the given Viewer.

You should call this function if you directly modify the 3D model associated with the Viewer. In such a case, it's more efficient to call this function than Q3Viewer_Draw, which also redraws other user interface elements (such as control buttons).

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_DrawControlStrip (
    TQ3ViewerObject theViewer
);

Discussion

Redraws the user interface controls of the given Viewer.

Call this function when you want to redraw the controls, without re-rendering the 3D view.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_EditClear (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Clear editing command.

Call this function in response to the user selecting the standard Clear command when the viewer has the focus.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_EditCopy (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Copy editing command.

Call this function in response to the user selecting the standard Copy command when the viewer has the focus.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_EditCut (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Cut editing command.

Call this function in response to the user selecting the standard Cut command when the viewer has the focus.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_EditPaste (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Paste editing command.

Call this function in response to the user selecting the standard Paste command when the viewer has the focus.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_EditUndo (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Undo editing command.

Call this function in response to the user selecting the standard Undo command when the viewer has the focus.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Boolean ) Q3Viewer_EventKeyboard (
    TQ3ViewerObject theViewer,
    const void *theEvent
);

Discussion

Should be called to handle a key-down, key-up, or auto-key event within the viewer when the viewer has the focus.

On Mac OS, theEvent should be a pointer to an EventRecord for the event. On Windows, this function is not currently supported.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theEvent

The keyboard event.

vPos

Vertical global (screen) location of mouse down.

function result

Returns as the Viewer handled the event.

( TQ3Boolean ) Q3Viewer_EventMouseDown (
    TQ3ViewerObject theViewer,
    TQ3Int32 hPos,
    TQ3Int32 vPos
);

Discussion

Should be called to handle a mouse-down event within the viewer.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

hPos

Horizontal global (screen) location of mouse down.

vPos

Vertical global (screen) location of mouse down.

function result

Returns as the Viewer handled the event.

( TQ3Boolean ) Q3Viewer_EventMouseTrack (
    TQ3ViewerObject theViewer,
    TQ3Int32 hPos,
    TQ3Int32 vPos
);

Discussion

Should be called to handle a mouse-move event within the viewer after a previous call to Q3Viewer_EventMouseDown has returned true.

Should be called repeatedly until the mouse is released.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

hPos

Horizontal global (screen) location of mouse.

vPos

Vertical global (screen) location of mouse.

function result

Returns as the Viewer handled the event.

( TQ3Boolean ) Q3Viewer_EventMouseUp (
    TQ3ViewerObject theViewer,
    TQ3Int32 hPos,
    TQ3Int32 vPos
);

Discussion

Should be called to handle a mouse-up event within the viewer after a previous call to Q3Viewer_EventMouseDown has returned true.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

hPos

Horizontal global (screen) location of mouse up.

vPos

Vertical global (screen) location of mouse up.

function result

Returns as the Viewer handled the event.

( TQ3Status ) Q3Viewer_GetBackgroundColor (
    TQ3ViewerObject theViewer,
    TQ3ColorARGB *theColor
);

Discussion

Gets the background color of a viewer.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theColor

Receives the background colour of the viewer.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_GetBounds (
    TQ3ViewerObject theViewer,
    TQ3Area *theRect
);

Discussion

Gets the current bounding rectangle of the Viewer pane.

The bounding rectangle determines where the Viewer draws itself within its window. The bounds are in window coordinates, and include both the rendered area and the control strip.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theRect

Receives the bounding rectangle within the window.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_GetBrightness (
    TQ3ViewerObject theViewer,
    float *theBrightness
);

Discussion

Gets the the intensity of lighting used on the model.

The brightness is specified as a float, ranging from 0.0 for no illumination to 1.0 for full illumination.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theBrightness

Receives the current brightness.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_GetButtonRect (
    TQ3ViewerObject theViewer,
    TQ3Uns32 theButton,
    TQ3Area *theRect
);

Discussion

Gets the rectangle that encloses a Viewer control button.

E.g., to obtain the location of the camera button within a viewer's control strip, use the kQ3ViewerButtonCamera constant.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theButton

The button to query.

theRect

Receives the rectangle covered by the button.

function result

Success or failure of the operation.

( TQ3ViewerDrawCallbackMethod ) Q3Viewer_GetCallbackDraw (
    TQ3ViewerObject theViewer
);

Discussion

Gets the current post-drawing callback for the viewer.

If no callback has been set, will return NULL.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

The current post-drawing callback.

( TQ3ViewerWindowResizeCallbackMethod ) Q3Viewer_GetCallbackResize (
    TQ3ViewerObject theViewer
);

Discussion

Gets the current resizing callback for the viewer.

If no callback has been set, will return NULL.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

The current resizing callback.

( TQ3ViewerPaneResizeNotifyCallbackMethod ) Q3Viewer_GetCallbackResizeNotify (
    TQ3ViewerObject theViewer
);

Discussion

Gets the current resize notification callback for the viewer.

If no callback has been set, will return NULL.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

The current resize notification callback.

( TQ3Status ) Q3Viewer_GetCameraCount (
    TQ3ViewerObject theViewer,
    TQ3Uns32 *cameraCount
);

Discussion

Returns how many cameras are supplied by the Viewer's view hints.

Model files may contain view hints which provide things such as "good" camera positions. This function will report how many such cameras are suggested. If there are no view hints associated with the Viewer, then this function returns 0.

See also Q3Viewer_SetCameraByNumber.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

cameraCount

Receives the camera count.

function result

Success or failure of the operation.

( void * ) Q3Viewer_GetControlStripWindow (
    TQ3ViewerObject theViewer
);

Discussion

Gets the window into which the viewer control strip draws.

On Mac OS, the window returned will be the WindowRef used by the main viewer. On Windows, it will be an HWND for the child window used by the control strip.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

The window used by the viewer.

( TQ3Uns32 ) Q3Viewer_GetCurrentButton (
    TQ3ViewerObject theViewer
);

Discussion

Gets the currently selected mode button of a viewer.

A Viewer object always has a "mode" which determines how mouse drags in the content area are interpreted. Modes are selected by clicking on one of the mode buttons; this function tells you which one is currently active. The result will be one of the following:

kQ3ViewerFlagButtonTruck kQ3ViewerFlagButtonOrbit kQ3ViewerFlagButtonZoom kQ3ViewerFlagButtonDolly

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

The currently active mode button.

( TQ3Status ) Q3Viewer_GetDimension (
    TQ3ViewerObject theViewer,
    TQ3Uns32 *theWidth,
    TQ3Uns32 *theHeight
);

Discussion

Get the dimensions of model space in a Viewer's view hints object.

If the specified Viewer has no view hints, then this function just returns the actual width and height of the viewer pane.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theWidth

Receives the hinted width.

theHeight

Receives the hinted height.

function result

Success or failure of the operation.

( TQ3Uns32 ) Q3Viewer_GetFlags (
    TQ3ViewerObject theViewer
);

Discussion

Gets the flags for a viewer.

Note that Q3Viewer_GetFlags returns kQ3ViewerFlagXXXX constants, not the QuickDraw 3D style kQ3ViewerXXXX constants.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Current feature flags.

( TQ3GroupObject ) Q3Viewer_GetGroup (
    TQ3ViewerObject theViewer
);

Discussion

Returns a reference to the 3D model data being used by the Viewer.

The reference count of the TQ3GroupObject returned is incremented by this call. Therefore, you should call Q3Object_Dispose on the returned object when you're with it.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Group containing 3D model data.

( void * ) Q3Viewer_GetImage (
    TQ3ViewerObject theViewer
);

Discussion

Gets a 2D copy of the current Viewer image, which can be copied to the clipboard or saved to a file.

On Mac OS, the pointer returned is to a PicHandle. This handle must be disposed of with DisposeHandle by the caller when no longer required.

On Windows, the pointer returned is to an HBITMAP. This must be disposed of by the caller when no longer required.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

The 2D image currently displayed by the viewer.

( TQ3Status ) Q3Viewer_GetMinimumDimension (
    TQ3ViewerObject theViewer,
    TQ3Uns32 *theWidth,
    TQ3Uns32 *theHeight
);

Discussion

Gets the minimum allowable size of the viewer pane.

The returned size will take into account the currently displayed buttons in the controller strip. If you allow the viewer pane (or its window) to be resized, you should not allow it to be resized smaller than the values returned by this function.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theWidth

Receives the minimum viewer width.

theHeight

Receives the minimum viewer height.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_GetPhongShading (
    TQ3ViewerObject theViewer,
    TQ3Boolean *phongShading
);

Discussion

Gets the current phong shading state of a Viewer.

Phong shading is generally slower but produces a more realistic effect, particularly where highlights are concerned.

Not all renderers support phong shading. Even if phong shading is turned on, the renderer may choose to ignore it when producing the image.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

phongShading

Receives the current phong shading state.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_GetReleaseVersion (
    TQ3Uns32 *releaseRevision
);

Discussion

Returns the version number of the Quesa viewer, in 'vers' format.

The four bytes contain 1) the major revision level, 2) the minor revision, 3) the development stage, and 4) the prerelease revision level, respectively. The three revision levels are each represented in binary coded decimal. The development stage can be development (0x20), alpha (0x40), beta (0x60) or release (0x80).

For example, if the revision is 1.61a23 (= 1.6.1a23), returns 0x01614023. For more information, see the description of the 'vers' resource in the book Inside Macintosh: Macintosh Toolbox Essentials.

See also the Q3Viewer_GetVersion function.

This function is not available in QD3D.

Parameter Descriptions

releaseRevision

Receives the version data.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_GetRemoveBackfaces (
    TQ3ViewerObject theViewer,
    TQ3Boolean *removeBackfaces
);

Discussion

Gets the current backface removal state of a Viewer.

Use this function to discover how the Viewer handles polygons which face away from the camera. If backface removal is on, such polygons will not be drawn. If it is off then all polygons are drawn, even if they face away from the camera.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

removeBackfaces

Receives the current backfacing state.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_GetRendererType (
    TQ3ViewerObject theViewer,
    TQ3ObjectType *rendererType
);

Discussion

Gets the renderer type currently used by the Viewer.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

rendererType

Receives the current renderer type.

function result

Success or failure of the operation.

( TQ3Uns32 ) Q3Viewer_GetState (
    TQ3ViewerObject theViewer
);

Discussion

Returns a set of status bits indicating the viewer state.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

The viewer status.

( TQ3Boolean ) Q3Viewer_GetUndoString (
    TQ3ViewerObject theViewer,
    char *theBuffer,
    TQ3Uns32 *bufferSize
);

Discussion

Gets text for the current Undo operation.

This function stores the name of the current Undoable operation in the user-supplied character buffer. The text should be localized to the user's preferred language (but probably is not, in Quesa 1.6 at least). Note that this text does not contain the "Undo" word itself, but only the name of the operation. So if you want to use this to set the text of a menu item, you'll need to prefix it with "Undo " yourself.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theBuffer

Pointer to a character buffer.

bufferSize

On entry, the buffer size; on exit, the text length.

function result

Returns as there is an Undoable operation.

( TQ3Status ) Q3Viewer_GetVersion (
    TQ3Uns32 *majorRevision,
    TQ3Uns32 *minorRevision
);

Discussion

Returns the major and minor version number of the Quesa viewer.

For example, if the revision is 1.6a23 (= 1.6.0a23), returns 1 as the major revision level and 6 as the minor revision level: The final 0 in the minor revision level is omitted. If the revision is 1.61a23 (= 1.6.1a23), returns 1 as the major revision level and 61 as the minor revision level.

See also the Q3Viewer_GetReleaseVersion function.

This function is not available in QD3D.

Parameter Descriptions

majorRevision

Receives the major version number.

minorRevision

Receives the minor version number.

function result

Success or failure of the operation.

( TQ3ViewObject ) Q3Viewer_GetView (
    TQ3ViewerObject theViewer
);

Discussion

Returns the view object associated with the given Viewer.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

View object associated with this Viewer.

( TQ3ViewerObject ) Q3Viewer_GetViewer (
    const void *theWindow
);

Discussion

Obtains the viewer object, if any, which is associated with a window.

If more than one viewer is using a window, the result is undefined: a valid viewer object will be returned, however it may not be the first viewer associated with the window.

On Mac OS, the window parameter should be a WindowRef. On Windows, it should be an HWND.

This function is not available in QD3D.

Parameter Descriptions

theWindow

The window to query.

function result

The associated viewer, or NULL if no viewer was found.

( void * ) Q3Viewer_GetWindow (
    TQ3ViewerObject theViewer
);

Discussion

Gets the window into which the viewer draws.

If NULL is returned, the viewer is not associated with any window.

On Mac OS, the window returned will be a WindowRef. On Windows, it will be an HWND.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

The window used by the viewer.

( TQ3ViewerObject ) Q3Viewer_New (
    const void *theWindow,
    const TQ3Area *theRect,
    TQ3Uns32 theFlags
);

Discussion

Creates a new Viewer object.

Q3Viewer_New will automatically initialise Quesa if it has not alreay been initialised, as per QD3D's Q3ViewerNew function. If you rely on this behaviour, you must dispose of the viewer object using Q3Viewer_Dispose to allow Quesa to be terminated when the last viewer is destroyed.

If your application initialises Quesa before creating a viewer object, the viewer can be disposed of with either Q3Viewer_Dispose or Q3Object_Dispose.

On Windows, the window parameter should be an HWND. On Mac OS, it should be a CGrafPtr (which you can get from a WindowRef via GetWindowPort).

Note that Q3Viewer_New takes kQ3ViewerFlagXXXX constants for theFlags, and not QD3D's old kQ3ViewerXXXX constants.

This function is not available in QD3D.

Parameter Descriptions

theWindow

The window to which the viewer should be attached.

theRect

Area of bounding rectangle within the window.

theFlags

Flags for the viewer. Use kQ3ViewerFlagDefault for the default attributes.

function result

Newly created Viewer object, or NULL if the Viewer could not be created.

( TQ3Status ) Q3Viewer_RestoreView (
    TQ3ViewerObject theViewer
);

Discussion

Resets the viewer camera according to the settings in the associated view hints object. If there are no view hints, resets the camera to a standard default state.

This has the same effect as clicking the reset button in the viewer controls.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetBackgroundColor (
    TQ3ViewerObject theViewer,
    const TQ3ColorARGB *theColor
);

Discussion

Sets the background color of a viewer.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theColor

The new background colour.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetBounds (
    TQ3ViewerObject theViewer,
    const TQ3Area *theRect
);

Discussion

Sets the bounding rectangle for the Viewer pane.

The bounding rectangle determines where the Viewer draws itself within its window. The bounds are in window coordinates, and include both the rendered area and the control strip.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theRect

The new bounding rectangle within the window.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetBrightness (
    TQ3ViewerObject theViewer,
    float theBrightness
);

Discussion

Sets the the intensity of lighting used on the model.

The brightness is specified as a float, ranging from 0.0 for no illumination to 1.0 for full illumination.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theBrightness

The desired brightness.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetCallbackDraw (
    TQ3ViewerObject theViewer,
    TQ3ViewerDrawCallbackMethod theCallback,
    const void *userData
);

Discussion

Sets a post-drawing callback for the viewer.

The callback is invoked by the viewer after it draws any part of itself, including the control strip. The userData parameter will be supplied to the callback unchanged.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theCallback

Pointer to a post-drawing callback.

userData

A pointer passed to the callback routine.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetCallbackResize (
    TQ3ViewerObject theViewer,
    TQ3ViewerWindowResizeCallbackMethod theCallback,
    const void *userData
);

Discussion

Sets a resizing callback for the viewer.

The callback is invoked by the viewer when the user clicks and drags in the resize region for its window. By default, the viewer will handle this operation and resize the window, however this callback can be used to override this behaviour.

The callback should handle all mouse tracking, resizing, and invalidating of the viewer window.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theCallback

Pointer to a resize callback.

userData

A pointer passed to the callback routine.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetCallbackResizeNotify (
    TQ3ViewerObject theViewer,
    TQ3ViewerPaneResizeNotifyCallbackMethod theCallback,
    const void *userData
);

Discussion

Sets a resize notification callback for the viewer.

The callback is invoked by the viewer when its window is resized.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theCallback

Pointer to a resize notification callback.

userData

A pointer passed to the callback routine.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetCameraByNumber (
    TQ3ViewerObject theViewer,
    TQ3Uns32 cameraIndex
);

Discussion

Sets the view to a camera in the Viewer's view hints.

Model files may contain view hints which provide things such as "good" camera positions. This function selects one of those cameras. The camera number supplied is 1-based, and the value must be less than or equal to the result of Q3Viewer_GetCameraCount.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

cameraIndex

1-based index of camera to select.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetCameraByView (
    TQ3ViewerObject theViewer,
    TQ3ViewerCameraView viewType
);

Discussion

Sets the camera to one of the predefined views.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

viewType

A constant selecting one of the predefined views.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetCurrentButton (
    TQ3ViewerObject theViewer,
    TQ3Uns32 theButton
);

Discussion

Sets the currently selected mode button of a viewer.

A Viewer object always has a "mode" which determines how mouse drags in the content area are interpreted. Modes are selected by clicking on one of the mode buttons; this function has exactly the same effect as a click on the specified button. The button parameter should be one of the following:

kQ3ViewerFlagButtonTruck kQ3ViewerFlagButtonOrbit kQ3ViewerFlagButtonZoom kQ3ViewerFlagButtonDolly

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theButton

The button to make active.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetDimension (
    TQ3ViewerObject theViewer,
    TQ3Uns32 theWidth,
    TQ3Uns32 theHeight
);

Discussion

Sets the dimensions of model space in a Viewer's view hints object.

This might be useful if you were then going to write a 3DMF file of the Viewer data; presumably it could store this hint in that file.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theWidth

Desired width of the viewer pane.

theHeight

Desired height of the viewer pane.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetFlags (
    TQ3ViewerObject theViewer,
    TQ3Uns32 theFlags
);

Discussion

Sets the flags for a viewer.

Note that Q3Viewer_SetFlags requires kQ3ViewerFlagXXXX constants, not the QuickDraw 3D style kQ3ViewerXXXX constants.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theFlags

the Flags to set.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetPhongShading (
    TQ3ViewerObject theViewer,
    TQ3Boolean phongShading
);

Discussion

Sets the current phong shading state of a Viewer.

Phong shading is generally slower but produces a more realistic effect, particularly where highlights are concerned.

Not all renderers support phong shading. Even if phong shading is turned on, the renderer may choose to ignore it when producing the image.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

phongShading

The new phong shading state.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetRemoveBackfaces (
    TQ3ViewerObject theViewer,
    TQ3Boolean removeBackfaces
);

Discussion

Sets the current backface removal state of a Viewer.

Use this function to control how the Viewer handles polygons which face away from the camera. If backface removal is on, such polygons will not be drawn. If it is off then all polygons are drawn, even if they face away from the camera.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

removeBackfaces

The new backfacing state.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetRendererType (
    TQ3ViewerObject theViewer,
    TQ3ObjectType rendererType
);

Discussion

Sets the renderer type used by the Viewer.

Calling this function is equivalent to selecting one of the renderers from the pop-up menu on the Options control button. The object type must be associated with one of the installed renderers.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

rendererType

Type of renderer to use.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_SetWindow (
    TQ3ViewerObject theViewer,
    const void *theWindow
);

Discussion

Sets the window into which the viewer draws.

On Mac OS, the window parameter should be a WindowRef. On Windows, it should be an HWND.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theWindow

The window to which the viewer should draw.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_UseData (
    TQ3ViewerObject theViewer,
    const void *theData,
    TQ3Uns32 dataSize
);

Discussion

Loads 3D scene data in memory into the Viewer.

The given data buffer is copied by the Viewer; the caller is responsible for disposing of it and may do so immediately after this call.

See also: Q3Viewer_UseFile and Q3Viewer_UseGroup.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theData

Pointer to a buffer containing scene data.

dataSize

Length of the data buffer in bytes.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_UseFile (
    TQ3ViewerObject theViewer,
    TQ3Uns32 fileRef
);

Discussion

Load data from a 3D model file into the Viewer.

On Mac OS, the file reference parameter should be a Mac OS file reference obtained from, e.g., FSOpen. On Windows, it should be a HANDLE to the open file. The file must be opened for reading.

See also: Q3Viewer_UseData and Q3Viewer_UseGroup.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

fileRef

Reference to a file opened for reading.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_UseGroup (
    TQ3ViewerObject theViewer,
    TQ3GroupObject theGroup
);

Discussion

Loads 3D scene data within a TQ3GroupObject into the Viewer.

See also: Q3Viewer_UseFile, Q3Viewer_UseData.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theGroup

Model data to load.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_WriteData (
    TQ3ViewerObject theViewer,
    void **theData,
    TQ3Uns32 *dataSize
);

Discussion

Flattens the 3D scene contained by the viewer into an internal block of data and provides access to that data.

The pointer returned is to memory allocated internally by the viewer. This memory must not be disposed of by your application, and will be released when the viewer object is disposed of.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

theData

Receives a pointer to a buffer containing the scene data.

dataSize

Receives the length of the data buffer in bytes.

function result

Success or failure of the operation.

( TQ3Status ) Q3Viewer_WriteFile (
    TQ3ViewerObject theViewer,
    TQ3Uns32 fileRef
);

Discussion

Write the 3D model data contained by the Viewer out to a file.

On Mac OS, the file reference parameter should be a Mac OS file reference obtained from, e.g., FSOpen. On Windows, it should be a HANDLE to the open file. The file must be opened for writing.

This function is not available in QD3D.

Parameter Descriptions

theViewer

Viewer object.

fileRef

Reference to a file opened for writing.

function result

Success or failure of the operation.

( TQ3Boolean ) Q3WinViewerAdjustCursor (
    TQ3ViewerObject theViewer,
    long x,
    long y
);

Discussion

Adjusts the mouse cursor if it's over the specified Viewer.

Call this function when the mouse moves, if it might be over the specified Viewer (or even if it's not). That gives the Viewer the opportunity to change the cursor as appropriate for the Viewer mode and cursor location.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

x

X location of the cursor, in local (window) coordinates.

y

Y location of the cursor, in local (window) coordinates.

function result

True if the cursor was changed, false otherwise.

( TQ3Status ) Q3WinViewerClear (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Clear editing command.

Call this function in response to the user selecting the standard Clear command when the viewer has the focus.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( BOOL ) Q3WinViewerContinueTracking (
    TQ3ViewerObject viewer,
    long x,
    long y
);

Discussion

Will be called upon mouse dragging in the content.

It is the answer of the viewer window to a WM_MOUSEMOVE message in in the content when the mouse button is down. Normally it will not be called from some user program.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

x

The x coordinate of the pointer.

y

The y coordinate of the pointer.

function result

Success indicator.

( TQ3Status ) Q3WinViewerCopy (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Copy editing command.

Call this function in response to the user selecting the standard Copy command when the viewer has the focus.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerCursorChanged (
    TQ3ViewerObject theViewer
);

Discussion

Notifies the Viewer that you have changed the cursor.

If you change the cursor (using SetCursor or similar), notify all active Viewers by calling this function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerCut (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Cut editing command.

Call this function in response to the user selecting the standard Cut command when the viewer has the focus.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerDispose (
    TQ3ViewerObject viewer
);

Discussion

Free all resources for the viewer window.

You call this routine before destroying the parent viewer of the viewer.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

Your viewer which you did create with Q3WinViewerNew.

function result

Normally kQ3Success, kQ3Failure if you input an invalid viewer.

( TQ3Status ) Q3WinViewerDraw (
    TQ3ViewerObject viewer
);

Discussion

Draw the content of the viewer and the control strip.

Call this function whenever you think that the normal windows update mechanisms do not show the current status of your 3D viewer.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

function result

Success indicator.

( TQ3Status ) Q3WinViewerDrawContent (
    TQ3ViewerObject viewer
);

Discussion

Draw the 3D world.

Call this function whenever you think that the normal windows update mechanisms do not show the current status of your 3D world.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

function result

Success indicator.

( TQ3Status ) Q3WinViewerDrawControlStrip (
    TQ3ViewerObject viewer
);

Discussion

Redraw the content of the viewer and the control strip.

Call this function whenever you think that the normal windows update mechanisms do not show the current status of your control strip.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

function result

Success indicator.

( TQ3Status ) Q3WinViewerGetBackgroundColor (
    TQ3ViewerObject viewer,
    TQ3ColorARGB *color
);

Discussion

Inquires the current flat background color of your 3D viewer.

Example: COLORREF RGB; if (Q3WinViewerGetBackgroundColor (gViewer, &color) == kQ3Failure) return false; rgb= RGB((BYTE)color.r * 255.0F,(BYTE)color.g * 255.0F, (BYTE)color.b * 255.0F);

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

color

A Quesa argb color in the 0..1 box.

function result

Success indicator.

( HBITMAP ) Q3WinViewerGetBitmap (
    TQ3ViewerObject viewer
);

Discussion

Returns a bitmap photo of your 3D world.

The dimension of the bitmap will correspond to your current viewer size. The color depth of the bitmap will correspond to your current screen resolution.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

function result

The bitmap, if successful, or NULL.

( TQ3Status ) Q3WinViewerGetBounds (
    TQ3ViewerObject viewer,
    RECT *bounds
);

Discussion

Inquires the current position of the viewer window.

The resulting bounds do include the screen space for the control strip.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

bounds

The current place of the viewer window in the parent window.

function result

Success indicator.

( TQ3Status ) Q3WinViewerGetButtonRect (
    TQ3ViewerObject theViewer,
    unsigned long button,
    RECT *rectangle
);

Discussion

Gets the rectangle that encloses a Viewer control button.

Specify the button of interest with one of the following constants:

kQ3ViewerButtonCamera kQ3ViewerButtonTruck kQ3ViewerButtonOrbit kQ3ViewerButtonZoom kQ3ViewerButtonDolly kQ3ViewerButtonReset kQ3ViewerButtonOptions

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

button

Which button to get (e.g., kQ3ViewerButtonCamera).

rect

Address of a rectangle to stuff with button bounds.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerGetCameraCount (
    TQ3ViewerObject viewer,
    unsigned long *count
);

Discussion

Returns how many cameras are supplied by the Viewer's view hints.

Model files may contain view hints which provide things such as "good" camera positions. This function will report how many such cameras are suggested. If there are no view hints associated with the Viewer, then this function returns 0.

See also Q3ViewerSetCameraByNumber.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

count

Address of integer to receive the camera count.

function result

Success or failure of the operation.

( HWND ) Q3WinViewerGetControlStrip (
    TQ3ViewerObject viewer
);

Discussion

Inquires the child window handle of the control strip.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

function result

The handle to the child window of the viewer, or zero, if not successful.

( unsigned long ) Q3WinViewerGetCurrentButton (
    TQ3ViewerObject theViewer
);

Discussion

Gets the currently selected mode button of the given Viewer.

A Viewer object always has a "mode" which determines how mouse drags in the content area are interpreted. Modes are selected by clicking on one of the mode buttons; this function tells you which one is currently active. The result will be one of the following:

kQ3ViewerButtonTruck kQ3ViewerButtonOrbit kQ3ViewerButtonZoom kQ3ViewerButtonDolly

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Active mode button.

( TQ3Status ) Q3WinViewerGetDimension (
    TQ3ViewerObject viewer,
    unsigned long *width,
    unsigned long *height
);

Discussion

Inquires the extent of the viewer window.

The resulting size does include the screen space for the control strip.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

width

The current width of the viewer window.

height

The current height of the viewer window.

function result

Success indicator.

( unsigned long ) Q3WinViewerGetFlags (
    TQ3ViewerObject theViewer
);

Discussion

Gets the Viewer feature flags currently in effect.

See Q3ViewerSetFlags for a listing of the possible flags.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Current feature flags.

( TQ3GroupObject ) Q3WinViewerGetGroup (
    TQ3ViewerObject theViewer
);

Discussion

Returns a reference to the 3D model data being used by the Viewer.

The reference count of the TQ3GroupObject returned is incremented by this call. Therefore, you should call Q3Object_Dispose on this value when you're with it.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Group containing 3D model data.

( TQ3Status ) Q3WinViewerGetMinimumDimension (
    TQ3ViewerObject theViewer,
    unsigned long *width,
    unsigned long *height
);

Discussion

Gets the minimum allowable size of the viewer pane.

The returned size will take into account the currently displayed buttons in the controller strip. If you allow the viewer pane (or its window) to be resized, you should not allow it to be resized smaller than the values returned by this function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

width

Address of an integer to receive the minimum viewer width.

height

Address of an integer to receive the minimum viewer height.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerGetReleaseVersion (
    unsigned long *releaseRevision
);

Discussion

Returns the version number of the Quesa viewer, in 'vers' format.

The four bytes contain 1) the major revision level, 2) the minor revision, 3) the development stage, and 4) the prerelease revision level, respectively. The three revision levels are each represented in binary coded decimal. The development stage can be development (0x20), alpha (0x40), beta (0x60) or release (0x80).

For example, if the revision is 1.61a23 (= 1.6.1a23), returns 0x01614023. For more information, see the description of the 'vers' resource in the book Inside Macintosh: Macintosh Toolbox Essentials.

See also the Q3ViewerGetVersion function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

releaseRevision

Address of integer to receive version data.

function result

Success or failure of the operation.

( unsigned long ) Q3WinViewerGetState (
    TQ3ViewerObject theViewer
);

Discussion

Returns a set of status bits indicating the viewer state.

The bits returned will be some combination of the following: kQ3ViewerEmpty: no image is currently displayed kQ3ViewerHasModel: an image of a 3D model is currently displayed kQ3ViewerHasUndo: the Viewer is able to undo a recent action

You might use these flags to enable the appropriate items of the Edit menu, for example.

See also the Q3ViewerGetUndoString function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

The current viewer state.

( TQ3Boolean ) Q3WinViewerGetUndoString (
    TQ3ViewerObject viewer,
    char *theString,
    unsigned long stringSize,
    unsigned long *actualSize
);

Discussion

Gets text for the current Undo operation.

This function stores the name of the current Undoable operation in the user-supplied character buffer. The text should be localized to the user's preferred language (but probably is not, in Quesa 1.6 at least). Note that this text does not contain the "Undo" word itself, but only the name of the operation. So if you want to use this to set the text of a menu item, you'll need to combine it with "Undo " yourself.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

theString

Receives the undo string.

stringSize

Size of buffer pointed to by theString.

actualSize

Number of bytes written to theString.

function result

True if there is an Undoable operation; false otherwise.

( TQ3Status ) Q3WinViewerGetVersion (
    unsigned long *majorRevision,
    unsigned long *minorRevision
);

Discussion

Returns the major and minor version number of the Quesa viewer.

For example, if the revision is 1.6a23 (= 1.6.0a23), returns 1 as the major revision level and 6 as the minor revision level: The final 0 in the minor revision level is omitted. If the revision is 1.61a23 (= 1.6.1a23), returns 1 as the major revision level and 61 as the minor revision level.

See also the Q3ViewerGetReleaseVersion function.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

majorRevision

Address of integer to receive major version number.

minorRevision

Address of integer to receive major version number.

function result

Success or failure of the operation.

( TQ3ViewObject ) Q3WinViewerGetView (
    TQ3ViewerObject theViewer
);

Discussion

Returns the view object associated with the given Viewer.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

View object associated with this Viewer.

( TQ3ViewerObject ) Q3WinViewerGetViewer (
    HWND theWindow
);

Discussion

Inquires a viewer which is associated to the given window.

The reference count of the viewer will not be increased.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theWindow

Your window.

function result

The viewer, or NULL, if not successful.

( HWND ) Q3WinViewerGetWindow (
    TQ3ViewerObject viewer
);

Discussion

Inquires the child window handle of the viewer.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

function result

The handle to the child window of the viewer, or zero, if not successful.

( BOOL ) Q3WinViewerMouseDown (
    TQ3ViewerObject viewer,
    long x,
    long y
);

Discussion

Will be called upon a mouse click in the content.

It is the answer of the viewer window to a WM_LBUTTONDOWN message in in the content. Normally it will not be called from some user program.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

x

The x coordinate of the pointer.

y

The y coordinate of the pointer.

function result

Success indicator.

( BOOL ) Q3WinViewerMouseUp (
    TQ3ViewerObject viewer,
    long x,
    long y
);

Discussion

Will be called upon a mouse release in the content.

It is the answer of the viewer window to a WM_LBUTTONUP message in in the content. Normally it will not be called from some user program.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

x

The x coordinate of the pointer.

y

The y coordinate of the pointer.

function result

Success indicator.

( TQ3ViewerObject ) Q3WinViewerNew (
    HWND window,
    const RECT *rect,
    unsigned long flags
);

Discussion

Create a new viewer in your window.

At creation time of your window (WM_CREATE) you call this routine to create the viewer, which is a child window, e.g.

RECT aWinRect; GetClientRect(hWnd, (LPRECT)&aWinRect); theViewer = Q3WinViewerNew (yourWnd, &aWinRect, kQ3ViewerDefault);

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

window

The parent window.

rect

The client rect in the parent window.

flags

The viewer style.

function result

The reference to a new viewer object on success, else 0.

( TQ3Status ) Q3WinViewerPaste (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Paste editing command.

Call this function in response to the user selecting the standard Paste command when the viewer has the focus.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerRestoreView (
    TQ3ViewerObject theViewer
);

Discussion

Resets the viewer camera according to the settings in the associated view hints object. If there are no view hints, resets the camera to a standard default state.

This has the same effect as clicking the reset button in the viewer controls.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerSetBackgroundColor (
    TQ3ViewerObject viewer,
    TQ3ColorARGB *color
);

Discussion

Sets the flat background color of your 3D viewer.

Example: TQ3ColorARGB color; DWORD rgb; // 32-bit RGB value rgb= myFavoriteColor(); color.a = 1.0F; color.r = (float)GetRValue(rgb)/(float)255; color.g = (float)GetGValue(rgb)/(float)255; color.b = (float)GetBValue(rgb)/(float)255; Q3WinViewerSetBackgroundColor (theViewer, &color);

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

color

A Quesa argb color in the 0..1 box.

function result

Success indicator.

( TQ3Status ) Q3WinViewerSetBounds (
    TQ3ViewerObject theViewer,
    RECT *bounds
);

Discussion

Sets the bounding rectangle for the Viewer pane.

Call this function to change where the Viewer draws itself within its window. The bounds are in window coordinates, with (0,0) being the top-left corner of the window.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

bounds

Address of a Rect containing new desired bounds

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerSetCameraNumber (
    TQ3ViewerObject viewer,
    unsigned long cameraNum
);

Discussion

Sets the view to a camera in the Viewer's view hints.

Model files may contain view hints which provide things such as "good" camera positions. This function selects one of those cameras. The camera number supplied is 1-based, and the value must be less than or equal to the result of Q3ViewerGetCameraCount.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

cameraNum

1-based index of camera to select.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerSetCameraView (
    TQ3ViewerObject viewer,
    TQ3ViewerCameraView viewType
);

Discussion

Sets the camera to one of the predefined views.

Possible values for viewType are: kQ3ViewerCameraRestore -- reset to initial position kQ3ViewerCameraFit -- fit entire model in the view kQ3ViewerCameraFront -- look at the front of the model kQ3ViewerCameraBack -- look at the back of the model kQ3ViewerCameraLeft -- look at the left side of the model kQ3ViewerCameraRight -- look at the right side of the model kQ3ViewerCameraTop -- look down at the top of the model kQ3ViewerCameraBottom -- look up at the bottom of the model

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

viewType

A constant selecting one of the predefined views.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerSetCurrentButton (
    TQ3ViewerObject theViewer,
    unsigned long button
);

Discussion

Sets the currently selected mode button of the given Viewer.

A Viewer object always has a "mode" which determines how mouse drags in the content area are interpreted. Modes are selected by clicking on one of the mode buttons; this function has exactly the same effect as a click on the specified button. The button parameter should be one of the following:

kQ3ViewerButtonTruck kQ3ViewerButtonOrbit kQ3ViewerButtonZoom kQ3ViewerButtonDolly

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

button

Constant indicating a mode button.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerSetDimension (
    TQ3ViewerObject viewer,
    unsigned long width,
    unsigned long height
);

Discussion

Sets the extent of the viewer window.

It does not change the anchor of the window, therefore you typically call this upon a resize of the parent window.

The size does include the screen space for the control strip.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

A valid viewer.

width

The new width of the viewer window.

height

The new height of the viewer window.

function result

Success indicator.

( TQ3Status ) Q3WinViewerSetFlags (
    TQ3ViewerObject theViewer,
    unsigned long flags
);

Discussion

Sets the Viewer feature flags. Flags are as follows:

kQ3ViewerShowBadge: If set, a badge is displayed when the controller strip is not visible. kQ3ViewerActive: Indicates that the viewer is active (rather than deactivated). kQ3ViewerControllerVisible: If set, the controller strip is visible. kQ3ViewerDrawFrame: If set, a one-pixel frame is drawn within the viewer pane. kQ3ViewerDraggingOff: If set, drag and drop is turned off (both dragging in and dragging out). kQ3ViewerButtonCamera: If set, the camera viewpoint control is displayed in the controller strip. kQ3ViewerButtonTruck: If set, the distance mode button is displayed in the controller strip. kQ3ViewerButtonOrbit: If set, the rotate mode button is displayed in the controller strip. kQ3ViewerButtonZoom: If set, the zoom mode button is displayed in the controller strip. kQ3ViewerButtonDolly: If set, the move (translate) mode button is displayed in the controller strip. kQ3ViewerButtonReset: If set, the reset button is displayed in the controller strip. kQ3ViewerOutputTextMode: If set, the Q3ViewerWriteFile function writes 3DMF data in text mode rather than binary. (Note: not currently supported!) kQ3ViewerDragMode: If set, the viewer is in drag and drop mode, causing it to respond only to drag and drop interaction. kQ3ViewerDrawGrowBox: If set, a grow (resize) box is drawn in the lower-right corner of the viewer pane. kQ3ViewerDrawDragBorder: If set, a drag border is drawn around the border of the rendering pane. The user can then initiate a drag by grabbing this border with the mouse. kQ3ViewerDraggingInOff: If set, dragging into the viewer pane is disabled. kQ3ViewerDraggingOutOff: If set, dragging out of the viewer pane is disabled. kQ3ViewerButtonOptions: If set, the options button is displayed in the controller strip. kQ3ViewerPaneGrowBox: ? kQ3ViewerDefault: Represents the default Viewer configuration.

Changes to the Viewer's flags will not be visible until the Viewer is redrawn (e.g., by calling Q3ViewerDraw).

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

flags

Desired combination of feature flags.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerSetWindow (
    TQ3ViewerObject viewer,
    HWND window
);

Discussion

Set the window into which the viewer should draw.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

The viewer to update.

window

The window for the viewer.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerUndo (
    TQ3ViewerObject theViewer
);

Discussion

Executes the Undo editing command.

Call this function in response to the user selecting the standard Undo command when the viewer has the focus.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerUseData (
    TQ3ViewerObject viewer,
    void *data,
    unsigned long size
);

Discussion

Loads 3D model data in memory into the Viewer.

The given data buffer is copied by the Viewer; the caller is responsible for disposing of it and may do so immediately after this call.

See also: Q3ViewerUseFile, Q3ViewerUseGroup.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

viewer

Viewer object.

data

Pointer to a buffer containing model data.

size

Length of the data buffer (in bytes).

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerUseFile (
    TQ3ViewerObject viewer,
    HANDLE fileHandle
);

Discussion

Load data from a 3D model file into the Viewer.

See also: Q3ViewerUseData, Q3ViewerUseGroup.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

fileHandle

Windows file HANDLE.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerUseGroup (
    TQ3ViewerObject theViewer,
    TQ3GroupObject group
);

Discussion

Loads a model data in a TQ3Group into the specified Viewer.

See also: Q3ViewerUseFile, Q3ViewerUseData.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

group

Model data to load.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerWriteData (
    TQ3ViewerObject theViewer,
    void *data,
    unsigned long dataSize,
    unsigned long *actualDataSize
);

Discussion

Copies the 3D model data contained by the viewer into a buffer.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

data

Receives the 3D model data.

dataSize

The size of buffer pointed to by data.

actualDataSize

Receives the number of bytes written to data.

function result

Success or failure of the operation.

( TQ3Status ) Q3WinViewerWriteFile (
    TQ3ViewerObject theViewer,
    HANDLE fileHandle
);

Discussion

Write the 3D model data contained by the Viewer out to a file.

Note - the QD3D Viewer API is deprecated in favour of the Quesa Viewer.

Parameter Descriptions

theViewer

Viewer object.

fileHandle

Windows file handle.

function result

Success or failure of the operation.

© 1999-2008 Quesa Developers (Last Updated 5/10/2008)