N3DCamera

N3DCamera

Inherits From: View : Responder : Object

Declared In: 3Dkit/N3DCamera.h

Class Description

N3DCamera is the 3D Graphics Kit's link to the Application Kit's event-handling and display mechanisms. N3DCamera is a subclass of View that adds methods for managing and performing both Interactive and PhotoRealistic RenderMan rendering.

PostScript and RenderMan Drawing
An N3DCamera draws both 2D and 3D images in response to a display message. The lockFocus method focuses both the Display PostScript interpreter and the Interactive RenderMan renderer on the camera. N3DCamera's drawSelf:: works by synchronizing previous PostScript drawing in the view hierarchy, sending a render: message to the camera's world shape (described in the next section), and finally sending itself a drawPS:: message to perform custom PostScript drawing over the RenderMan rendering.
In other View subclasses, you override the drawSelf:: method to perform PostScript drawing. In N3DCamera, you override the drawPS:: method.

The World Shape
The N3DCamera has a pointer to a single N3DShape object--its world shape--that serves as the origin of the coordinate system for the scene viewed by the camera. Since both the camera and the world shape may be transformed (translated, scaled, rotated) independently, the world origin can be thought of as existing between the transformation applied to the N3DCamera and that applied to its world shape.
The world shape is at the top of the hierarchy of shapes potentially visible to the camera. The N3DShape class description includes a discussion of the shape hierarchy, as well as a diagram showing the relationships between camera, world shape, and shape hierarchy.
A camera can be connected to any N3DShape in a shape hierarchy. This allows you to view just a part of a scene by setting the camera's world shape to the shape whose descendants you wish to view. You can also have several cameras viewing the same shapes, from different points of view, by setting each camera's world shape to the same N3DShape.

The Camera Coordinate System
The camera's position is initially defined in terms of the world coordinate system. The camera's view point defines a point in world coordinates at the center of the scene viewed by the camera. The camera's eye point defines the camera's focal point in world coordinates. The line segment connecting the eye point to the view point is referred to as the eye-to-view-point vector.

Figure 17-1. World and camera coordinate systems

In the illustration above, the view point is at the origin of the world coordinate system (0.0, 0.0, 0.0) and the eye point is at a point (A_x, B_y, C_z), with A_xbeing 0.0, B_ybeing positive, and C_zbeing negative. By default, the N3DCamera has its eye point positioned at the origin of world space (0.0, 0.0, 0.0) and its view point at (0.0, 0.0, 1.0).
Also shown in the above illustration are the axes of the camera's coordinate system: the s-axis, t-axis, and u-axis. The camera's axes are shown more clearly in the following illustration:

Figure 17-2. Camera coordinates

The origin of the camera coordinate system is always at the eye point. The u-axis is always perpendicular to the camera's focal plane: it points along the eye-to-view-point vector. The s-axis aligns horizontally with the camera, running through the eye point, and the t-axis aligns vertically with the camera through the eye point. (Note that the camera's coordinate system is a left-handed coordinate system.)
The s-basis, u-basis and t-basis are points that define vectors (directed line segments) related to the camera coordinate system. These vectors define the units and orientation of the axes of the camera's coordinate system. The basis points are initialized by N3DCamera with s-basis at (1.0, 0.0, 0.0), t-basis at (0.0, 1.0, 0.0), u-basis at (0.0, 0.0, 1.0). With these settings, units in the camera coordinate system are equal to units in the world coordinate system.

Figure 17-3. Camera bases

The camera's roll defines its rotation about the u-basis. A positive roll angle produces counterclockwise rotation about this axis (as viewed by the camera), negative rotation produces clockwise rotation.

Global Lights
The camera's light list manages N3DLights that illuminate the whole scene viewed by the camera: the world shape, its peers, and its descendants.
Since N3DLight is a subclass of N3DShape, an N3DLight object can be both a descendant or peer of the world shape and a member of the list of global light. Since the light's position is determined by its position in the shape hierarchy, you can place a light at a specific point in the scene viewed by the camera. You can then make it a global light, causing it to illuminate all shapes visible in the scene, even those above it in the shape hierarchy.
A global light need not belong to the shape hierarchy viewed by the camera. You could, for example, create an instance of N3DLight and add it to the global light list. Such a light would by default have a coordinate system that matched the world coordinate system. You could then use a method such as getEyeAt:toward:roll: to get the coordinates needed to position this light relative to the camera.

Determining Rendering Order
The camera's hider determines the order in which surfaces are rendered. Which hider is appropriate depends on the type of surface being rendered and the drawing performance desired. The 3D Kit defines three hider types (in the header file /NextDeveloper/Headers/3Dkit/next3d.h):

Hider Type Surface Type Performance

N3D_HiddenRendering solids slower

N3D_InOrderRendering wireframe, point cloud faster

N3D_NoRendering any fastest

N3D_HiddenRendering performs standard hidden-surface computations using a z-buffer. N3D_InOrderRendering renders objects in the order in which they are defined in the camera's RIB stream; this is the default setting. N3D_NoRendering produces no image. The methods hider and setHider: manage the hider type used by the camera. The method setSurfaceTypeForAll:chooseHider: can be used to select the appropriate hider for a particular surface type.

The Camera's Delegate
The camera's delegate implements a method to handle image streams rendered by the PhotoRealistic RenderMan renderer. The methods renderAsEPS and renderAsTIFF initiate photorealistic rendering, and the delegate receives the resulting image stream in a message from the 3D Kit when rendering is complete.

Instance Variables

unsigned int globalWindowNum;
RtToken windowResource;
N3DProjectionType projectionType;
RtToken contextToken;
id worldShape;
List *lightList;
id delegate;
NXColor backgroundColor;
N3DHider hider;
struct _cameraFlags {
unsigned int degenerate:1;
unsigned int windowChanged:1;
unsigned int needsWindow:1;
unsigned int basisChanged:1;
unsigned int canRender:1;
unsigned int usePreTM:1;
unsigned int doFlush:1;
unsigned int inWorldBlock:1;
unsigned int drawBackground:1;
cameraFlags;
struct _projectionRectangle {
float l, r, t, b;
} projectionRectangle;
RtPoint eyePoint;
RtPoint viewPoint;
float rollAngle;
float fov;
float pixelAspectRatio;
float nearPlane;
float farPlane;
RtPoint sBasis;
RtPoint tBasis;
RtPoint uBasis;
RtMatrix preTransform;
RtMatrix transform;

globalWindowNum Server global window number

windowResource Camera's RenderMan resource token

projectionType Camera's projection type

contextToken Camera's RenderMan context token

worldShape Top of the shape hierarchy viewed by the camera

lightList Global N3DLight List

delegate Camera's delegate

backgroundColor Color filled in bounds behind 3D imaging

hider The hider used for interactive rendering

cameraFlags.degenerate YES if the N3DCamera is 0 width or height

cameraFlags.windowChanged YES if camera changed windows

cameraFlags.needsWindow YES if camera isn't in a window's view hierarchy

cameraFlags.basisChanged YES if camera's coordinates changed

cameraFlags.canRender YES if the camera has all resources for rendering

cameraFlags.usePreTM YES if transform is premultiplied by preTransform when rendering

cameraFlags.doFlush YES if the render method sends a flushRIB message

cameraFlags.inWorldBlock YES if inside WorldBegin()...WorldEnd() block

cameraFlags.drawBackground YES if backgroundColor is filled in before rendering

projectionRectangle.l Horizontal coordinate of left edge of projection rectangle

projectionRectangle.r Horizontal coordinate of right edge of projection rectangle

projectionRectangle.t Vertical coordinate of top edge of projection rectangle

projectionRectangle.b Vertical coordinate of bottom edge of projection rectangle

eyePoint, viewPoint Endpoints of viewing vector

rollAngle Angle of negative rotation about viewing vector

fov Angle of viewing frustum

pixelAspectRatio Width/height ratio of pixels

nearPlane Distance from eye to near clipping plane

farPlane Distance from eye to far clipping plane

sBasis Vector defining camera's horizontal axis

tBasis Vector defining camera's vertical axis

uBasis Vector defining camera's longitudinal axis

preTransform Matrix for premultiplication

transform Matrix for world-to-camera transformation

Method Types

Initializing and freeing init

initFrame:
free

Rendering RIB render

renderSelf:
setFlushRIB:
doesFlushRIB
flushRIB

Drawing PostScript lockFocus

unlockFocus
drawPS::
drawSelf::

Background color setBackgroundColor:

backgroundColor
setDrawBackgroundColor:
doesDrawBackgroundColor

Modifying the frame rectangle moveBy::

moveTo::
rotateBy:
rotateTo:
setFrame:
sizeBy::
sizeTo::

Managing the shape hierarchy setWorldShape:

worldShape

Managing global lights addLight:

removeLight:
lightList

Picking selectShapesIn:

Projection rectangle setProjectionRectangle::::

getProjectionRectangle::::

Selecting projection type setProjection:

projectionType

Pretransform matrix setPreTransformMatrix:

getPreTransformMatrix:
setUsePreTransformMatrix:
usesPreTransformMatrix

Eye position manipulation setEyeAt:toward:roll:

getEyeAt:toward:roll:
moveEyeBy:::
rotateEyeBy::about:

Clipping planes setClipPlanesNear:far:

getClipPlanesNear:far:

Field of view setFieldOfViewByAngle:

setFieldOfViewByFocalLength:
fieldOfView

Pixel aspect ratio setPixelAspectRatio:

pixelAspectRatio

Converting coordinates convertPoints:count:fromSpace:

convertPoints:count:toWorld:

Frame number frameNumber

Printing canPrintRIB

Copying RIB copyRIBCode:

Setting world attributes worldBegin:

worldEnd:

Setting and getting the delegate setDelegate:

delegate

Setting the hider hider

setHider:
setSurfaceTypeForAll:chooseHider:

Rendering photorealistically renderAsEPS

renderAsTIFF
numCropWindows
cropInRects:nRects:

Archiving awake

read:
write:

Instance Methods

addLight:

addLight:aLight

Adds aLight to the N3DCamera's light list and sets it to be a global light. Global lights are rendered before all other N3DShapes in the scene viewed by the camera; thus, they potentially illuminate the entire scene (depending on the type of the light). Returns self.
If aLight is in a shape hierarchy, it remains in that hierarchy, and its origin is determined by any transformations applied by the hierarchy. If not, its origin is the origin of the world coordinate system.
See also: lightList, removeLight:, setGlobal: (N3DLight), isGlobal (N3DLight)

awake

awake

Invoked after unarchiving to allow the N3DCamera to perform additional initialization. Returns self.
See also: read:, write:

backgroundColor

(NXColor)backgroundColor

Returns the background color--the color filled behind all drawing, both 2D and 3D, performed by the camera. The default value is NX_COLORBLACK.
See also: doesDrawBackgroundColor, setBackgroundColor:,
setDrawBackgroundColor:

canPrintRIB

(BOOL)canPrintRIB

Returns YES. This method is invoked for each View in a View hierarchy when printing to determine if any RIB needs to be rendered by the PhotoRealistic RenderMan renderer.

convertPoints:count:fromSpace:

convertPoints:(RtPoint *)points

count:(int)n
fromSpace:aShape

Converts the elements in points, an array of RtPoints specified in the coordinate system of aShape, to the two-dimensional (Display PostScript) coordinate system of the receiver. On return, the first two elements of each RtPoint in points represents an x-y coordinate pair in the receiver's coordinate system; the third element should be ignored. Returns self, and by reference, the transformed points.
This method may be useful for hit detection, for direct manipulation of N3DShapes displayed in the N3DCamera, and for positioning PostScript drawing relative to N3DShapes displayed.
See also: convertPoints:count:toWorld:

convertPoints:count:toWorld:

convertPoints:(NXPoint *)mcoords

count:(int)pointCount
toWorld:(RtPoint *)wcoords

Converts each 2D point in mcoords from the receiver's coordinate system to a pair of 3D points in world-coordinates. For each 3D point pair returned in wcoords, the first point's z-value places it at the near clipping plane, and the second point's z-value places it at the far clipping plane. wcoords should point to an array of RtPoints large enough to hold twice pointCount.
Returns self and, by reference in wcoords, the 3D point pairs. A NULL pointer returned in wcoords indicates that the N3DCamera has been unable to convert the points.
This method may be useful for hit detection, for direct manipulation of N3DShapes displayed in the N3DCamera, and for positioning shapes relative to PostScript drawing.
See also: convertPoints:count:fromSpace:

copyRIBCode:

copyRIBCode:(NXStream *)stream

Copies the RIB code generated by the receiver to stream. Use this method to generate data for a ".rib" file or an NX_RIBPasteboardType. The RIB code copied to stream includes that generated by the receiver and by any visible shapes in its world shape's hierarchy. Returns self.

cropInRects:nRects:

cropInRects:(NXRect *)theRects nRects:(int)rectCount

Returns self and, by reference in theRects, an array of rectCount rectangles representing horizontal strips of the camera's area. This method is used by the kit when rendering on multiple rendering hosts. Override this method if you want an N3DCamera's image to be divided in some other way for rendering on multiple hosts.
See also: numCropWindows

delegate

delegate

Returns the receiver's delegate. An N3DCamera's delegate will be notified by a camera:didRenderStream:tag:frameNumber: message when a frame generated by the renderAsEPS or renderAsTIFF methods has been rendered.
See also: renderAsEPS, renderAsTIFF,
camera:didRenderStream:tag:frameNumber: (delegate method)

doesDrawBackgroundColor

(BOOL)doesDrawBackgroundColor

Returns YES if the background color will be drawn in the bounds rectangle by drawSelf:: before any other rendering or drawing is done in the N3DCamera; returns NO otherwise. The default return value is YES.
See also: backgroundColor, setBackgroundColor:, setDrawBackgroundColor:

doesFlushRIB

(BOOL)doesFlushRIB

Returns YES if the N3DCamera's render method flushes the RIB pipeline, waiting to return until all rendering is complete. RIB is flushed by sending a flushRIB message after rendering the N3DCamera's global lights, world shape, and shape hierarchy. The default return value is YES.
See also: flushRIB, setFlushRIB:, render

drawPS::

drawPS:(NXRect *)rects :(int)nRects

Abstract method for PostScript drawing in an N3DCamera. Override this method rather than drawSelf:: to do PostScript drawing in an N3DCamera. This method is invoked by N3DCamera's drawSelf:: method, which passes along its rects and nRects arguments; thus you can structure the code in this method exactly as you would the code in a View's drawSelf:: method. PostScript drawing is done "on the glass" in front of any RenderMan drawing in the view. Returns self.
See also: drawSelf::, render, renderSelf:

drawSelf::

drawSelf:(const NXRect *)rects :(int)nRects

Overridden by N3DCamera to perform both PostScript and RenderMan drawing each time the camera is displayed. This method first draws the current background color if the N3DCamera is set to do so. It then redraws all shapes in the N3DCamera's shape hierarchy, clipping the rendering to the first rectangle in rects, if any. Finally, it invokes drawPS:: to do PostScript drawing in the View. Returns self.
Unlike other View subclasses, you don't override this method to do custom drawing in a subclass of N3DCamera. Instead, you override the abstract method drawPS::. If you override this method, be sure to invoke drawSelf:: on super.
See also: drawPS::, render, renderSelf:, backgroundColor, doesDrawBackgroundColor: - setBackgroundColor:, setDrawBackgroundColor:

fieldOfView

(float)fieldOfView

Returns the field of view for the N3DCamera: the angle in degrees of the viewing frustum. The default field of view is 40 degrees.
See also: setFieldOfViewByAngle:, setFieldOfViewByFocalLength:

flushRIB

flushRIB

Assures that all rendering is completed before execution continues. This method is comparable to the Application Kit function NXPing(). Returns self.
See also: doesFlushRIB, setFlushRIB:

frameNumber

(int)frameNumber

Returns 1. This method is invoked when rendering to get the value to pass in the RenderMan RiFrame() function. It's overridden by N3DMovieCamera for multiple frame animation.
See also: frameNumber (N3DMovieCamera)

free

free

Frees the N3DCamera and its associated storage. Doesn't free the camera's world shape or list of global lights. Invokes free on super and returns the value returned by that message.
See also: initFrame:

getClipPlanesNear:far:

getClipPlanesNear:(float *)aNearPlane far:(float *)aFarPlane

Returns self and, by reference, the distances from the eye point to the clipping planes for the camera's viewing frustum. aNearPlane and aFarPlane should each be allocated to the size of a single float. The values returned represent the distance in world coordinates along a line extending through the eye-to-view-point vector, with the origin (0.0) at the eye point. The default values are 0.01 (near) and 1000.0 (far). Returns self.
See also: setClipPlanesNear:far:

getEyeAt:toward:roll:

getEyeAt:(RtPoint *)eyePoint

toward:(RtPoint *)viewPoint
roll:(float *)rollAngle

Returns self and, by reference in eyePoint and viewPoint, the eye-to-view-point vector. The values returned are in world coordinates. rollAngle indicates rotation about this vector, with positive values representing counterclockwise rotation (looking through the camera) and negative values representing clockwise rotation. The default eyePoint is (0.0, 0.0, 0.0)--the origin of the world coordinate system. The default viewPoint is (0.0, 0.0, 1.0)--viewing along the z-axis. The default rollAngle is 0.0.
See also: setEyeAt:toward:roll:

getPreTransformMatrix:

getPreTransformMatrix:(RtMatrix)theMatrix

Returns self and, in theMatrix, the camera's pretransform matrix. By default, a camera has no pretransform matrix.
See also: setPreTransformMatrix:, setUsePreTransformMatrix:,
usesPreTransformMatrix

getProjectionRectangle::::

getProjectionRectangle:(float *)left

:(float *)right
:(float *)top
:(float *)bottom

Returns self and, by reference in left, right, top, and bottom, the RenderMan screen window extent. These are the values passed to the RenderMan RiScreenWindow() function when the camera renders. The default values are -1.0 (left), 1.0 (right), 1.0 (top), and -1.0 (bottom).
See also: setProjectionRectangle::::

hider

(N3DHider)hider

Returns the receiver's N3DHider. The returned value represents the technique used to arrange objects in the N3DCamera's image. The 3D Kit defines three hider types (in the header file 3Dkit/next3d.h):

N3D_HiddenRendering
N3D_InOrderRendering
N3D_NoRendering

See "Determining Rendering Order" in the class description for a discussion of the hider types.
See also: setHider:

init

init

Invokes initFrame: with NULL as the argument.
See also: initFrame:

initFrame:

initFrame:(const NXRect *)fRect

Initializes the N3DCamera by first invoking initFrame: on super, then setting instance variables and starting the context for 3D rendering with Interactive RenderMan.
This method sets the N3DCamera's context token to that of the N3DContextManager's main context. It allocates a default world shape, sets the background color to NX_COLORBLACK, sets the global window number to zero, and sets the projection type to N3D_Perspective. It sets the eye point to (0.0, 0.0, 0.0) and sets the view point to (0.0, 0.0, 1.0). This aims the camera directly along the z-axis from the origin of world coordinates, the RenderMan default for camera position. It sets the near clipping plane to 0.01 and the far clipping plane to 1000.0.
This method is the designated initializer for N3DCamera. Returns self.
See also: initFrame: (View)

lightList

lightList

Returns the List object that manages the N3DCamera's global light sources--N3DLight objects that illuminate the entire scene viewed by the camera. N3DCamera allocates this list lazily, the first time you invoke addLight:. You may want to get at objects in this list for certain lighting effects--like turning lights on or off. You shouldn't add objects to or remove objects from this list using List methods; instead use N3DCamera's addLight: and removeLight: methods.
See also: addLight:, removeLight:, isGlobal (N3DLight), setGlobal: (N3DLight)

lockFocus

(BOOL)lockFocus

Locks PostScript focus on the View, then invokes the RenderMan RiDisplay() function to focus rendering on the window and frame buffer in which the camera is drawn. It also recalculates the projection rectangle to assure that 3D rendering occurs within the correct camera coordinate system. Returns the value returned by super's lockFocus.
See also: unlockFocus

moveBy::

moveBy:(NXCoord)deltaX :(NXCoord)deltaY

Overridden to ensure that adjustments to the camera's two-dimensional (PostScript) coordinate system are reflected in its three-dimensional (RenderMan) coordinate system.
This method repositions the view within its superview's coordinate system by invoking super's moveBy:: method. It then recalculates the 3D coordinate system by invoking RiDisplay() and adjusting the projection rectangle to match the new extent of the 2D coordinate system. Returns self.
See also: moveTo::

moveEyeBy:::

moveEyeBy:(float)sDistance :(float)tDistance :(float)uDistance

Moves the camera along its own axes. sDistance determines the horizontal movement, tDistance determines vertical movement, and uDistance determines movement along the axis defined by the eye-to-view-point vector. See the class description for an illustration of these camera axes. Returns self.
See also: moveBy::, moveTo::

moveTo::

moveTo:(NXCoord)x :(NXCoord)y

Overridden to ensure that adjustments to the camera's two-dimensional (PostScript) coordinate system are reflected in its three-dimensional (RenderMan) coordinate system.
This method repositions the view within its superview's coordinate system by invoking super's moveTo:: method. It then recalculates the 3D coordinate system by invoking RiDisplay() and adjusting the projection rectangle to match the new origin of the 2D coordinate system. Returns self.
See also: moveBy::

numCropWindows

(int)numCropWindows

Returns the number of horizontal rectangles that the camera image will be divided into for PhotoRealistic RenderMan rendering on multiple hosts. This method is invoked by the 3D Kit when printing; the return value is determined by the number of rendering hosts selected.
Override this method if you want the N3DCamera's image to be rendered in some other number of rectangles. You might, for example, want the user to be able to select the number and size of divisions of an image to be rendered.
See also: cropInRects:nRects:, numSelectedHosts (N3DRenderPanel)

pixelAspectRatio

(float)pixelAspectRatio

Returns the pixel aspect ratio for the N3DCamera. The default value is 1.0.
See also: setPixelAspectRatio:

projectionType

(N3DProjectionType)projectionType

Returns the projection type for the N3DCamera. The projection type may be either N3D_Perspective (the default) or N3D_Orthographic, defined in the header file 3Dkit/next3d.h.
See also: setProjection:

read:

read:(NXTypedStream *)stream

Reads an instance of N3DCamera from stream. Returns self.
See also: awake, write:

removeLight:

removeLight:aLight

Removes aLight from the N3DCamera's light list by invoking List's removeObject: method and sending aLight a setGlobal: message with NO as the argument. Returns self.
See also: addLight:, lightList

render

render

Renders the camera, its world shape, and any shapes in the world shape's hierarchy. This method is invoked by N3DCamera's drawSelf:: method to perform 3D rendering whenever the camera is displayed. Invoke this method directly if you want the camera to perform only 3D drawing; be sure to lock focus on the camera before invoking render directly from your code.
This method clips 3D rendering to the rectangle returned by getVisibleRect:. It calls RiFrameBegin(), invoking the camera's frameNumber method for the argument to this function. It sets up the projection type and applies the camera's transformations, then invokes the worldBegin: method on self. It then does camera-specific rendering by invoking the camera's renderSelf: method, and renders the world shape, its descendants, and peers by invoking render: on the world shape. After rendering, it invokes worldEnd:, calls RiFrameEnd(), and returns self.
See also: getPreTransformMatrix:, setPreTransformMatrix:, frameNumber,
worldBegin:, worldEnd:

renderAsEPS

(int)renderAsEPS

Begins photorealistic rendering of the camera's image, and returns a unique integer tag by which the N3DCamera's delegate can identify the rendering job. This method runs the Render panel before rendering begins. The resulting image contains both PostScript and RenderMan drawing.
A photorealistic image is rendered by a separate process and can take some time to complete. The 3D Kit runs the PhotoRealistic RenderMan renderer asynchronously, and signals the N3DCamera's delegate when EPS image data has been generated, using the delegate's camera:didRenderStream:tag:frameNumber: method. The arguments to this method include a tag corresponding to that returned by renderAsEPS when the rendering began, the camera that initiated the rendering, and a stream containing the EPS image.
See also: renderAsTIFF, camera:didRenderStream:tag:frameNumber: (delegate method)

renderAsTIFF

(int)renderAsTIFF

Begins photorealistic rendering of the camera's image, and returns a unique integer tag by which the N3DCamera's delegate can identify the rendering job. This method runs the Render panel before rendering begins. The resulting image contains only RenderMan drawing.
A photorealistic image is rendered by a separate process and can take some time to complete. The 3D Kit runs the PhotoRealistic RenderMan renderer asynchronously, and signals the N3DCamera's delegate when TIFF image data has been generated, using the delegate's camera:didRenderStream:tag:frameNumber: method. The arguments to this method include a tag corresponding to that returned by renderAsTIFF when the rendering began, the camera that initiated the rendering, and a stream containing the TIFF image.
See also: renderAsEPS, camera:didRenderStream:tag:frameNumber: (delegate method)

renderSelf:

renderSelf:(RtToken)context

Does nothing, returns self. Override this abstract method to do camera-specific rendering in the N3DCamera. This method is invoked by N3DCamera's render method before the shapes in the world shape's hierarchy are rendered.
See also: drawPS::, drawSelf::, render

rotateBy:

rotateBy:(NXCoord)deltaAngle

Overridden by N3DCamera to prevent the view's 2D (PostScript) coordinate system from being rotated. Does nothing, returns self.
See also: rotateTo:

rotateEyeBy::about:

rotateEyeBy:(float)dElev :(float)dAzim about:(RtPoint)pivotPtr

Rotates the camera horizontally and vertically about the pivot point. This method performs this rotation by first performing an s-axis (horizontal) rotation by dElev, followed by a t-axis (vertical) rotation by dAzim of the eye vector. Both rotations are about pivotPtr, an RtPoint specified in world coordinates. See the class description for an illustration of the camera axes. Returns self.
See also: moveEyeBy:::

rotateTo:

rotateTo:(NXCoord)angle

Overridden by N3DCamera to prevent the 2D (PostScript) coordinate system from being rotated. Does nothing and returns self.
See also: rotateBy:

selectShapesIn:

selectShapesIn:(const NXRect *)selectionRect

Returns a List object containing N3DShapes visible in selectionRect. Only shapes that return YES in response to isSelectable are included in the List. selectionRect is in the 2D (PostScript) coordinate system of the receiving camera. The List object returned belongs to the Camera.
See also: isSelectable (N3DShape class), setSelectable: (N3DShape class)

setBackgroundColor:

setBackgroundColor:(NXColor)color

Sets the background color of the N3DCamera. The background color is drawn behind all other drawing--both RenderMan and PostScript--if the clearFrame flag is set. By default, the background color is NX_COLORBLACK. Returns self.
See also: backgroundColor, doesDrawBackgroundColor, setDrawBackgroundColor:

setClipPlanesNear:far:

setClipPlanesNear:(float)aNearPlane far:(float)aFarPlane

Sets the distances from the eye point to the clipping planes for the camera's viewing frustum. aNearPlane and aFarPlane represent distances from the eye point along a line extending through the eye-to-view-point vector. RI_EPSILON (a constant defined in the header file ri/ri.h) is the minimum value allowed for either argument; if either is smaller, RI_EPSILON is substituted. RI_INFINITY (also defined in ri/ri.h) is the maximum value allowed for either argument; if either is larger, RI_INFINITY is substituted. aNearPlane should always be less than aFarPlane--no 3D drawing can appear in the camera otherwise. Returns self.
See also: getClipPlanesNear:far:

setDelegate:

setDelegate:theDelegate

Sets the N3DCamera's delegate. theDelegate implements the method camera:didRenderStream:tag:frameNumber:, the method for getting photorealistic images rendered by renderAsEPS and renderAsTIFF methods. Returns self.
See also: delegate

setDrawBackgroundColor:

setDrawBackgroundColor:(BOOL)flag

If flag is YES, the background color will be drawn in the bounds rectangle before any other drawing is done in the N3DCamera. Returns self.
See also: backgroundColor, doesDrawBackgroundColor, setBackgroundColor:

setEyeAt:toward:roll:

setEyeAt:(RtPoint)fromPoint

toward:(RtPoint)toPoint
roll:(float)aRollAngle

Establishes the eye-to-view-point vector. toPoint is made the camera's view point, and fromPoint is set as the eye point. The standard camera transformation is then applied to rotate the camera by aRollAngle degrees around its eye-to-view-point vector. See the class description for a discussion of the camera coordinates and the eye-to-view-point vector. Returns self.
See also: getEyeAt:toward:roll:

setFieldOfViewByAngle:

setFieldOfViewByAngle:(float)viewAngle

Sets the field of view to viewAngle, the angle of the camera's viewing frustum in degrees. viewAngle should be between 0 and 180 degrees. Returns self.
See also: fieldOfView, setFieldOfViewByFocalLength:

setFieldOfViewByFocalLength:

setFieldOfViewByFocalLength:(float)aFocalLength

Calculates and sets the field of view as a function of focal length: the distance between the projection rectangle (the screen window in RenderMan terminology) and the eye point. The RenderMan standard actually fixes a camera's focal length at 1.0. Thus, if aFocalLength is greater than 1.0, this method zooms the camera's lens; if less than 1.0, this method widens the camera's lens. This method achieves the effect of setting focal length by calculating the N3DCamera's field of view from aFocalLength. Returns self.
See also: fieldOfView, setFieldOfViewByAngle:

setFlushRIB:

setFlushRIB:(BOOL)flag

If flag is YES, the camera's render method sends a flushRIB message to self after the camera and world shape hierarchy have been rendered. Returns self.
See also: doesFlushRIB, flushRIB

setFrame:

setFrame:(const NXRect *)fRect

Overridden to ensure that adjustments to the camera's two-dimensional (PostScript) coordinate system are reflected in its three-dimensional (RenderMan) coordinate system.
This method repositions and resizes the view within its superview's coordinate system by invoking super's setFrame: method. It then recalculates the 3D coordinate system by invoking RiDisplay() and adjusting the projection rectangle to match the new extent of the 2D coordinate system. Returns self.

setHider:

setHider:(N3DHider)theHider

Sets the receiver's N3DHider. theHider represents the technique used to arrange objects in the N3DCamera's image. The 3D Kit defines three N3DHider types in the header file 3Dkit/next3d.h:

N3D_HiddenRendering
N3D_InOrderRendering
N3D_NoRendering

See "Determining Rendering Order" in the class description for a discussion of the hider types.
See also: hider

setPixelAspectRatio:

setPixelAspectRatio:(float)theRatio

Sets the receiver's pixel aspect ratio to theRatio. The ratio for images rendered on most displays and printers is 1.0--the default setting. Use this method when rendering images for output on devices with non-square pixels. Values less than 1.0 indicate horizontal stretching of the pixel; values greater than 1.0 indicate vertical stretching. Returns self.
See also: pixelAspectRatio

setPreTransformMatrix:

setPreTransformMatrix:(RtMatrix)theMatrix

Sets the N3DCamera's pretransform matrix. theMatrix represents a 3D transformation that will be applied to the camera before its transform matrix is applied. Returns self.
See also: getPreTransformMatrix:, setUsePreTransformMatrix:, usesPreTransformMatrix

setProjection:

setProjection:(N3DProjectionType)aProjection

Sets the projection type for the N3DCamera. aProjection may be N3D_Perspective or N3D_Orthographic; these are defined in the header file 3Dkit/next3d.h. Returns self.
See also: projectionType

setProjectionRectangle::::

setProjectionRectangle:(float)left

:(float)right
:(float)top
:(float)bottom

Sets the camera's projection rectangle (the screen window in RenderMan terminology). These values are used in calls to the RenderMan RiScreenWindow() function when rendering and when converting points between the camera coordinate system and other coordinate systems. Returns self.
See also: getProjectionRectangle::::

setSurfaceTypeForAll:chooseHider:

setSurfaceTypeForAll:(N3DSurfaceType)surface chooseHider:(BOOL)flag

Sets the surface type for all shapes in the world shape's hierarchy. surface may be one of the N3DSurfaceTypes, defined in the header file 3Dkit/next3d.h:

N3D_PointCloud
N3D_WireFrame
N3D_ShadedWireFrame
N3D_FacetedSolids
N3D_SmoothSolids

If flag is YES, this method chooses the hider type most appropriate to surface: N3D_InOrder for N3D_PointCloud, N3D_WireFrame, and N3D_ShadedWireFrame; N3D_HiddenRendering for N3D_FacetedSolids and N3D_SmoothSolids.

setUsePreTransformMatrix:

setUsePreTransformMatrix:(BOOL)flag

If flag is YES, sets the receiver to apply its pretransform matrix before applying its transform matrix. When pretransformation is applied to the camera, it is transformed by the pretransform matrix and then by the transform matrix. By default, a camera has no pretransform matrix. Use the setPreTransformMatrix: method to set the pretransform matrix, then use this method to apply that matrix.
See also: getPreTransformMatrix:, setPreTransformMatrix:,
usesPreTransformMatrix

setWorldShape:

setWorldShape:a3DShape

Sets the receiver's world shape to a3DShape. Returns the previous world shape. This method doesn't apply the surface type set for the world shape and its hierarchy by a previous call to setSurfaceTypeForAll:chooseHider:--you must do so explicitly by again invoking that method.
See also: setSurfaceTypeForAll:chooseHider:, worldShape

sizeBy::

sizeBy:(NXCoord)deltaWidth :(NXCoord)deltaHeight

Overridden to ensure that adjustments to the camera's 2D (PostScript) coordinate system are reflected in its 3D (RenderMan) coordinate system.
This method repositions and resizes the view within its superview's coordinate system by invoking super's sizeBy:: method. It then recalculates the 3D coordinate system by invoking RiDisplay() and adjusting the projection rectangle to match the new extent of the 2D coordinate system. Returns self.
See also: sizeTo::

sizeTo::

sizeTo:(NXCoord)width :(NXCoord)height

Overridden to ensure that adjustments to the camera's 2D (PostScript) coordinate system are reflected in its 3D (RenderMan) coordinate system.
This method resizes the view within its superview's coordinate system by invoking super's sizeBy:: method. It then recalculates the 3D coordinate system by invoking RiDisplay() and adjusting the projection rectangle to match the new extent of the 2D coordinate system. Returns self.
See also: sizeBy::

unlockFocus

unlockFocus

Disables 3D rendering in the camera, then sends an unlockFocus message to super, returning the value returned by that message.
See also: lockFocus, drawPS:, drawSelf::, renderSelf:, render

usesPreTransformMatrix

(BOOL)usesPreTransformMatrix

Returns YES if the receiver applies its pretransform matrix before applying its transform matrix. Returns NO if the receiver applies only its transform matrix. By default, N3DCamera applies only the transform matrix.
See also: getPreTransformMatrix:, setPreTransformMatrix:,
setUsePreTransformMatrix

worldBegin:

worldBegin:(RtToken)theContext

Calls the RenderMan function RiWorldBegin(). Override this method to place other RenderMan function calls before RiWorldBegin(). Returns self.
You need to override this method to declare macros for use in photorealistic rendering. Macros are declared between the RenderMan procedures RiMacroBegin() and RiMacroEnd().
One simple use of macros in the 3D Kit is to have a world shape load a RIB file as a macro. To do so, you could implement the following createRIBMacro method in your N3DShape subclass, and invoke it when setting the camera's world shape:

char *ribFile; /* name of source file for RIB code */
RtToken ribFileResource, ribMacro; /* tokens for file and macro */
...
- createRIBMacro
{
ribFileResource = RiResource(ribFile, RI_ARCHIVE, RI_FILEPATH,
&ribFile, RI_NULL);
ribMacro = RiMacroBegin(ribFile, RI_NULL);
RiReadArchive(ribFileResource, NULL, RI_NULL);
RiMacroEnd();
return self;
}

Your N3DShape's renderSelf: method would be implemented as follows:

- renderSelf:camera
{
RiMacroInstance(ribMacro, RI_NULL);
return self;
}

However, the macro would be valid only in the Interactive Renderer context--that is, in the display context. To apply the macro when printing, you'd write a worldBegin: method like this:

- worldBegin:(RtToken)context
{
[super worldBegin:context];
if (NXDrawingStatus != NX_DRAWING)
[worldShape createRIBMacro];
return self;
}

You can also override worldBegin: to call RenderMan functions for setting camera options--such as RiDepthOfField(), RiShutter(), RiExposure(), and so on. Options are declared before the RiWorldBegin() call, so a worldBegin: method to set depth of field would be coded as follows:

- worldBegin:(RtToken)context
{
RiDepthOfField(myFstop, myFocalLength, myFocalDistance);
[super worldBegin:context];
return self
}

See also: worldEnd:

worldEnd:

worldEnd:(RtToken)theContext

Calls the RenderMan procedure RiWorldEnd(). You can override this method to clean up after a camera has rendered.
See also: worldBegin:

worldShape

worldShape

Returns the N3DCamera's world shape. By default, the camera allocates an N3DShape as its world shape.
See also: setWorldShape:

write:

write:(NXTypedStream *)stream

Writes the receiving N3DCamera to stream. Returns self.
See also: read:

Methods Implemented by the Delegate

camera:didRenderStream:tag:frameNumber:

camera:theCamera

didRenderStream:(NXStream *)imageStream
tag:(int)theJob
frameNumber:(int)currentFrame

Invoked by the 3D Kit when PhotoRealistic RenderMan rendering finishes. Your application initiates photorealistic rendering by invoking N3DCamera's renderAsEPS or renderAsTIFF method. Each time one of these methods is invoked, it returns a unique integer. The delegate can compare this number with the integer tag theJob to identify a rendering job.
Your delegate can handle the image returned by imageStream in a number of ways. It can, for example, write imageStream to a file or use it to initialize an NXImage:

- camera:theCamera didRenderStream:(NXStream *)imageStream
tag:(int)theJob frameNumber:(int)currentFrame
{
myImage = [[NXImage alloc] initFromStream:imageStream];
return self;
}

currentFrame represents the number returned by the initiating camera's frameNumber method. If theCamera is an N3DMovieCamera or subclass thereof, the rendering methods will produce all the frames for the scene; thus currentFrame reflects the frame number of the image being returned. If theCamera is an N3DCamera or subclass (other than N3DMovieCamera), the rendering methods produce a single frame; thus, currentFrame is usually 1.
Photoreal rendering can take some time. If an application exits before a rendering job is finished, this method won't be called and the rendered image will be lost.
See also: frameNumber, renderAsEPS, renderAsTIFF

	Inherits From:	View : Responder : Object

	Declared In:	3Dkit/N3DCamera.h

Hider Type	Surface Type	Performance

N3D_HiddenRendering	solids	slower
N3D_InOrderRendering	wireframe, point cloud	faster
N3D_NoRendering	any	fastest

	windowResource	Camera's RenderMan resource token

	projectionType	Camera's projection type

	contextToken	Camera's RenderMan context token

	worldShape	Top of the shape hierarchy viewed by the camera

	lightList	Global N3DLight List

	delegate	Camera's delegate

	backgroundColor	Color filled in bounds behind 3D imaging

	hider	The hider used for interactive rendering

	cameraFlags.degenerate	YES if the N3DCamera is 0 width or height

	cameraFlags.windowChanged	YES if camera changed windows

	cameraFlags.needsWindow	YES if camera isn't in a window's view hierarchy

	cameraFlags.basisChanged	YES if camera's coordinates changed

	cameraFlags.canRender	YES if the camera has all resources for rendering

	cameraFlags.usePreTM	YES if transform is premultiplied by preTransform when rendering

	cameraFlags.doFlush	YES if the render method sends a flushRIB message

	cameraFlags.inWorldBlock	YES if inside WorldBegin()...WorldEnd() block

	cameraFlags.drawBackground	YES if backgroundColor is filled in before rendering

	projectionRectangle.l	Horizontal coordinate of left edge of projection rectangle

	projectionRectangle.r	Horizontal coordinate of right edge of projection rectangle

	projectionRectangle.t	Vertical coordinate of top edge of projection rectangle

	projectionRectangle.b	Vertical coordinate of bottom edge of projection rectangle

	eyePoint, viewPoint	Endpoints of viewing vector

	rollAngle	Angle of negative rotation about viewing vector

	fov	Angle of viewing frustum

	pixelAspectRatio	Width/height ratio of pixels

	nearPlane	Distance from eye to near clipping plane

	farPlane	Distance from eye to far clipping plane

	sBasis	Vector defining camera's horizontal axis

	tBasis	Vector defining camera's vertical axis

	uBasis	Vector defining camera's longitudinal axis

	preTransform	Matrix for premultiplication

	transform	Matrix for world-to-camera transformation

	Picking	selectShapesIn:

	Projection rectangle	setProjectionRectangle::::

	Frame number	frameNumber

	Printing	canPrintRIB

	Copying RIB	copyRIBCode:

	Setting world attributes	worldBegin: