Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

17

3D Graphics Kit

Classes N3DCamera

Inherits From:

View : Responder : Object

Initializing and Freeing

	init	Initializes with 0 frame size
	initFrame:(const NXRect *)fRect	Initializes with specified frame size
	free	Frees the N3DCamera

All Drawing

	(BOOL)lockFocus	YES if PostScript and RenderMan drawing lock on camera
	unlockFocus	Unlocks PostScript and RenderMan drawing
	drawSelf:(NXRect *)rects :(int)nRects	Performs all RIB and PostScript drawing

RenderMan Drawing

	render	Renders the camera and any content shapes
	renderSelf:(RtToken)context	Override to perform custom rendering in the camera
	setFlushRIB:(BOOL)flag	Sets the receiver to invoke flushRIB within render
	doesFlushRIB	Tests whether the receiver invokes flushRIB within render
	flushRIB	Waits until all RIB code has been rendered

PostScript Drawing

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

Override to perform custom PostScript drawing

Background Color

	setBackgroundColor:(NXColor)color	Sets the NXColor filled behind all drawing
	(NXColor)backgroundColor	The NXColor filled behind all drawing
	setDrawBackgroundColor:(BOOL)flag	If flag is YES, fills color behind all drawing
	(BOOL)doesDrawBackgroundColor	YES if camera fills color behind all drawing

PostScript Transformation Management

	setFrame:(const NXRect *)fRect	Sets frame for both PostScript and RenderMan coordinate systems
	moveTo:(NXCoord)x :(NXCoord)y	Moves both PostScript and RenderMan coordinate systems
	moveBy:(NXCoord)deltaX :(NXCoord)deltaY	Moves both PostScript and RenderMan coordinate systems
	sizeTo:(NXCoord)width :(NXCoord)height	Resizes both PostScript and RenderMan coordinate systems
	sizeBy:(NXCoord)deltaWidth	Resizes both PostScript and RenderMan coordinate
	:(NXCoord)deltaHeight	systems
	rotateTo:(NXCoord)angle	Prevents rotation of PostScript coordinate system
	rotateBy:(NXCoord)deltaAngle	Prevents rotation of PostScript coordinate system

Shape Hierarchy Management

	setWorldShape:a3DShape	Sets world shape
	worldShape	Returns world shape

Global Light Management

	addLight:aLight	Adds an N3DLight to the camera's global light list
	removeLight:aLight	Removes an N3DLight to the camera's global light list
	lightList	Returns the camera's global light list

Picking

selectShapesIn:(const NXRect *)selectionRect

Returns a List of N3DShapes in selectionRect

Projection Rectangle

	setProjectionRectangle:(float)left	Sets the 3D coordinate system projection rectangle
	:(float)right
	:(float)top
	:(float)bottom
	getProjectionRectangle:(float *)left	Returns the 3D coordinate system's projection
	:(float *)right	rectangle
	:(float *)top
	:(float *)bottom

Selecting Projection Type

	setProjection:(N3DProjectionType)aProjection	Sets the projection type
	(N3DProjectionType)projectionType	Returns the projection type

Pretransform Matrix

	setPreTransformMatrix:(RtMatrix)theMatrix	Sets the camera's pretransformation matrix
	getPreTransformMatrix:(RtMatrix)theMatrix	Returns the camera's pretransformation matrix
	setUsePreTransformMatrix:(BOOL)flag	Sets the camera to use its pretransformation matrix
	(BOOL)usesPreTransformMatrix	YES if camera uses its pretransformation matrix

Setting Viewpoint

	setEyeAt:(RtPoint)fromPoint	Sets the eye-to-viewpoint vector and roll
	toward:(RtPoint)toPoint
	roll:(float)aRollAngle
	getEyeAt:(RtPoint *)fromPoint	Gets the eye-to-viewpoint vector and roll
	toward:(RtPoint *)toPoint
	roll:(float *)aRollAngle
	moveEyeBy:(float)sDistance	Moves camera in its own coordinate system
	:(float)tDistance
	:(float)uDistance
	rotateEyeBy:(float)dElev :(float)dAzim	Rotates the camera in its own coordinates
	about:(RtPoint)pivotPtr

Clipping Planes

	setClipPlanesNear:(float)aNearPlane	Sets the camera's near and far clipping planes
	far:(float)aFarPlane
	getClipPlanesNear:(float *)aNearPlane	Returns the camera's near and far clipping planes
	far:(float *)aFarPlane

Field of View

	setFieldOfViewByAngle:(float)viewAngle	Sets the viewing angle of the camera
	setFieldOfViewByFocalLength:(float)aLength	Converts a focal length into a viewing angle for the camera
	(float)fieldOfView	Returns the viewing angle of the camera

Pixel Aspect Ratio

	setPixelAspectRatio:(float)theRatio	Sets the pixel aspect ratio for the camera
	(float)pixelAspectRatio	Returns the pixel aspect ratio for the camera

Converting Coordinates

	convertPoints:(RtPoint *)points	Converts an array of points to PostScript coordinates
	count:(int)n
	fromSpace:aShape
	convertPoints:(NXPoint *)mcoords	Converts PostScript points to world coordinates
	count:(int)pointCount
	toWorld:(RtPoint *)wcoords

Crop Windows

	(int)numCropWindows	Count of rectangle divisions for photoreal rendering
	cropInRects:(NXRect *)theRects	Returns rectangles representing horizontal strips of
	nRects:(int)rectCount	camera image

Frame Number

(int)frameNumber

Returns 1

Printing

(BOOL)canPrintRIB

Returns YES

Copying RIB

copyRIBCode:(NXStream *)stream

Copies RIB code generated by the receiver

Setting World Attributes

	worldBegin:(RtToken)theContext	Calls RiWorldBegin()
	worldEnd:(RtToken)theContext	Calls RiWorldEnd()

Setting and Getting the Delegate

	setDelegate:cameraDelegate	Sets the receiver's delegate
	delegate	Returns the receiver's delegate

Setting the Hider

	(N3DHider)hider	Returns the receiver's N3DHider
	setHider:(N3DHider)cameraHider	Sets the receiver's N3DHider

setSurfaceTypeForAll:(N3DSurfaceType)surface

chooseHider:(BOOL)flag

Sets surface type for shapes in world shape hierarchy

Rendering Photorealistically

	(int)renderAsEPS	Begins rendering, returns identifier for rendering session
	(int)renderAsTIFF	Begins rendering, returns identifier for rendering session

Archiving

	read:(NXTypedStream *)theStream	Reads the camera from the stream
	write:(NXTypedStream *)theStream	Writes the camera to the stream
	awake	Performs additional initialization after unarchiving

Methods Implemented by the Delegate

camera:theCamera

Handles images generated by photoreal rendering

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

N3DContextManager

Inherits From:

Object

Initializing and Freeing

	+ new	Returns (creating if necessary) one instance per application
	free	Destroys all contexts, frees the receiver

Getting the Main Context

(RtToken)mainContext

Returns (creating if necessary) the application's main context

Creating Other Contexts

	(RtToken)createContext:(const char *)name	Creates a named context
	(RtToken)createContext:(const char *)name	Creates a named context for a specific renderer
	withRenderer:(RtToken)renderer
	(RtToken)createContext:(const char *)came	Creates a named context on a file
	toFile:(const char *)ribFile
	(RtToken)createContext:(const char *)name	Does nothing, returns NULL
	toStream:(NXStream *)stream

Managing the Current Context

	(RtToken)currentContext	The application's current context
	(RtToken)setCurrentContext:(RtToken)context	Sets the current context, returns previous context

(RtToken)setCurrentContextByName:(const char *)name

Sets the current context by name, returns previous context

Destroying a Context

(void)destroyContext:(RtToken)context

Destroys the context

(void)destroyContextByName:(const char *)name

Destroys a context with name

Archiving

awake

Performs additional initialization after unarchiving

N3DLight

Inherits From:

N3DShape : Object

Initializing

init

Initializes the receiver as an N3D_AmbientLight

Setting Light Type

	setType:(N3DLightType)aType	Sets the receiver's light type
	(N3DLightType)type	Returns the receiver's light type
	makeAmbientWithIntensity:(RtFloat)intensity	Sets type N3D_AmbientLight with appropriate parameter
	makePointFrom:(RtPoint)from	Sets type N3D_PointLight with appropriate
	intensity:(RtFloat)intensity	parameters
	makeDistantFrom:(RtPoint)fromPoint	Sets type N3D_PointLight with appropriate
	to:(RtPoint)toPoint	parameters
	intensity:(RtFloat)i
	makeSpotFrom:(RtPoint)fromPoint	Sets type N3D_SpotLight with appropriate parameters
	to:(RtPoint)toPoint
	coneAngle:(RtFloat)coneAngle
	coneDelta:(RtFloat)deltaAngle
	beamDistribution:(RtFloat)distribution
	intensity:(RtFloat)intensity

Setting Light Parameters

	setFrom:(RtPoint)fromPoint	Sets the from point
	setFrom:(RtPoint)fromPoint	Sets the from and to points
	to:(RtPoint)toPoint
	getFrom:(RtPoint *)fromPoint	Returns the from and to points
	to:(RtPoint *)toPoint
	setConeAngle:(RtFloat)coneAngle	Sets the cone angle, cone delta, and beam distribution
	coneDelta:(RtFloat)coneDelta
	beamDistribution:(RtFloat)distribution
	getConeAngle:(RtFloat *)coneAngle	Gets the cone angle, cone delta, and beam distribution
	coneDelta:(RtFloat *)coneDelta
	beamDistribution:(RtFloat *)distribution
	setIntensity:(RtFloat)intensity	Sets the intensity
	(RtFloat)intensity	Returns the intensity

Rendering

	renderSelf:(N3DCamera *)theCamera	Renders the light as a local light
	renderGlobal:(N3DCamera *)theCamera	Renders the light as a global light

Global Light Management

	setGlobal:(BOOL)flag	Override to add behavior on becoming/resigning global
	(BOOL)isGlobal	YES if light is global

Switching On and Off

switchLight:(BOOL)flag

If flag is YES, turns receiver on

Setting Color

	setColor:(NXColor)theColor	Sets the receiver's color
	(NXColor)color	Returns the receiver's color

Archiving

	read:(NXTypedStream *)theStream	Reads the receiver from the stream
	write:(NXTypedStream *)theStream	Writes the receiver to the stream
	awake	Performs additional initialization after unarchiving

N3DMovieCamera

Inherits From:

N3DCamera : View : Responder : Object

Initializing

initFrame:(const NXRect *)fRect

Initializes the receiver

RenderMan Drawing

render

Renders current frame; if printing, renders current page

Interactive Display

displayMovie

Displays movie, first frame to last, onscreen

Frame Numbers

	setFrameNumber:(int)aFrameNumber	Sets the current frame number
	(int)frameNumber	Returns the current frame number
	setStartFrame:(int)start	Sets counters for movie
	endFrame:(int)end
	incrementFramesBy:(int)skip
	(int)startFrame	Returns the first frame number
	(int)endFrame	Returns the last frame number
	(int)frameIncrement	Returns the frame increment

Archiving

	read:(NXTypedStream *)theStream	Reads the receiver from the stream
	write:(NXTypedStream *)theStream	Writes the receiver to the stream
	awake	Performs additional initialization after unarchiving

N3DRenderPanel

Inherits From:

Panel : Window : Responder : Object

Initializing the Class

	+ initialize	Initializes the class with data from the defaults database
	+ new	Creates, if necessary, and returns an N3DRenderPanel

Setting Accessory View

	accessoryView	Returns the accessory view
	setAccessoryView:aView	Sets the accessory view

Running Modal

(int)runModal

Presents the render panel in a model loop

Resolution

(int)resolution

Returns the resolution set by the user in the panel

Host Management

	(int)numSelectedHosts	Returns the number of hosts selected by the user
	(char **)hostNames	Returns an array of strings for selected host names

Browser Delegate Method

	(int)browser:sender	Fills the panel's browser with host names
	fillMatrix:theMatrix
	inColumn:(int)col

N3DRIBImageRep

Inherits From:

NXImageRep : Object

Initializing and Freeing

	initFromFile:(const char *)ribfile	Initializes the receiver from a file
	initFromStream:(NXStream *)ribStream	Initializes the receiver from a stream
	free	Frees the receiver

Declaring Data Types

+ (const char *const *)imageUnfilteredFileTypes

Returns supported file types

+ (const NXAtom *)imageUnfilteredPasteboardTypes

Returns supported pasteboard types

+ (BOOL)canLoadFromStream:(NXStream *)theStream

Tests theStream for RIB data

Drawing

	(BOOL)drawAt:(const NXPoint *)point	Returns YES if the image is successfully drawn at point
	(BOOL)drawIn:(const NXRect *)rect	Returns YES if the image is successfully drawn in rect
	(BOOL)draw	Returns YES if the image is successfully drawn

Size

	getBoundingBox:(NXRect *)rectangle	Returns the rectangle that bounds the image
	getSize:(NXSize *)theSize	Returns the size of the image

Background Color

	(NXColor)backgroundColor	Returns the background color
	setBackgroundColor:(NXColor)theColor	Sets the background color

Hidden Surface Removal Type

	(N3DHider)hider	Returns the hider type for rendering images
	setHider:(N3DHider)theHider	Sets the hider type for rendering images

Surface Type

	setSurfaceType:(N3DSurfaceType)type	Sets the surface type used for rendering images
	(N3DSurfaceType)surfaceType	Returns the surface type used for rendering images

Archiving

	read:(NXTypedStream *)theStream	Reads the receiver from the stream
	write:(NXTypedStream *)theStream	Writes the receiver to the stream

N3DRotator

Inherits From:

Object

Initializing

	init	Initializes the receiver
	initWithCamera:myCamera	Initializes the receiver and sets its camera

Setting Parameters

	setCamera:myCamera	Sets the receiver's camera
	setCenter:(const NXPoint *)center	Sets the receiver's center point and radius
	andRadius:(float)radius

Axes of Rotation

	setRotationAxis:(N3DAxis)axis	Sets the axes about which the receiver rotates
	(N3DAxis)rotationAxis	Returns the axis about which the receiver rotates

Mouse Tracking

	trackMouseFrom:(const NXPoint *)lastPoint	Accepts two points in camera coordinates, returns
	to:(const NXPoint *)thisPoint	rotations based on their offset
	rotationMatrix:(RtMatrix)theRotation
	andInverse:(RtMatrix)theInverse

Archiving

	read:(NXTypedStream *)theStream	Reads the receiver from the stream
	write:(NXTypedStream *)theStream	Writes the receiver to the stream

N3DShader

Inherits From:

Object

Initializing and Freeing

	init	Initializes the receiver with no shader file
	initWithShader:(const char *)aShader	Initializes the receiver with a shader file
	free	Frees the receiver

Shader Language Object File

	setShader:(const char *)aShader	Sets the receiver's shader
	(const char *)shader	Returns the receiver's shader

Shader Color

	setColor:(NXColor)aColor	Sets the receiver's color
	(NXColor)color	Returns the receiver's color
	setUseColor:(BOOL)flag	Sets the receiver to apply its color
	(BOOL)doesUseColor	YES if receiver applies color

Shader Transparency

	setTransparency:(float)alphaValue	Sets the receiver's transparency
	(float)transparency	Returns the receiver's transparency

Shader Function Argument Handling

	(int)shaderArgCount	The number of arguments for the shader function
	(const char *)shaderArgNameAt:(int)argIndex	The name of the indicated argument

(SLO_TYPE)shaderArgType:(const char *)argName

The type of the named argument

	(BOOL)isShaderArg:(const char *)argName	YES if argName is an argument to the shader function
	setShaderArg:(const char *)floatName	Sets the specified argument to the specified value
	floatValue:(float)floatValue
	setShaderArg:(const char *)stringName	Sets the specified argument to the specified value
	stringValue:(const char *)stringValue
	setShaderArg:(const char *)pointName	Sets the specified argument to the specified value
	pointValue:(RtPoint)pointValue
	setShaderArg:(const char *)colorName	Sets the specified argument to the specified value
	colorValue:(NXColor)colorValue
	getShaderArg:(const char *)floatName	Gets the specified value for the specified argument
	floatValue:(float *)floatValue
	getShaderArg:(const char *)stringName	Gets the specified value for the specified argument
	stringValue:(const char **)stringValue
	getShaderArg:(const char *)pointName	Gets the specified value for the specified argument
	pointValue:(RtPoint *)pointValue
	getShaderArg:(const char *)colorName	Gets the specified value for the specified argument
	colorValue:(NXColor *)colorValue
	resetShaderArg:(const char *)argName	Resets the specified argument to its default value

Shader Type

(SLO_TYPE)shaderType

Returns the type of the shader

Setting

set

Applies the shader function during rendering

Archiving

	read:(NXTypedStream *)theStream	Reads the receiver from the stream
	write:(NXTypedStream *)theStream	Writes the receiver to the stream

N3DShape

Inherits From:

Object

Initializing and Freeing

	init	Initializes and returns the receiver
	free	Frees the receiver and its descendants
	freeAll	Frees the receiver, its next peer and its descendants

Rendering the N3DShape

	render:(N3DCamera *)theCamera	Renders the shape and its descendants
	renderSelf:(N3DCamera *)theCamera	Override to implement actual rendering
	renderSelfAsBox:(N3DCamera *)theCamera	Renders only the shape's bounding box

Traversing the Shape Hierarchy

	nextPeer	Returns the shape "to the right"
	previousPeer	Returns the shape "to the left"
	firstPeer	Returns the shape "to the far left" of receiver's peer group
	lastPeer	Returns the shape "to the far right" of receiver's peer group
	descendant	Returns the shape "below" the receiver
	lastDescendant	Returns the farthest descendant below the receiver
	ancestor	Returns the shape "above the receiver
	firstAncestor	Returns the shape at the top of the receiver's hierarchy
	(BOOL)isWorld	YES if the receiver is at the top of its hierarchy

Managing the Shape Hierarchy

	linkPeer:aPeer	Inserts aPeer between receiver and its next peer
	linkDescendant:aDescendant	Inserts aDescendant between receiver and its descendant
	linkAncestor:anAncestor	Sets receiver's ancestor, returns previous ancestor
	unlink	Unlinks the receiver, reconnects peers and descendants
	group:anAncestor	Makes the receiver a descendant of anAncestor
	ungroup	Removes receiver from hierarchy, promotes descendant

Shader

	setShader:aShader	Sets an N3DShader for the shape
	shaderType:(SLO_TYPE)type	Returns the N3DShader of type

Surface

	(N3DSurfaceType)surfaceType	Returns the receiver's surface type
	setSurfaceType:(N3DSurfaceType)theSurface	Sets receiver's surface type; if flag is YES, sets descendants
	andDescendants:(BOOL)flag	surface types

Bounding Box

	getBoundingBox:(RtBound *)boundingBox	Returns by reference the receiver's bounding box
	setDrawAsBox:(BOOL)flag	Sets the receiver to draw only its bounding box
	(BOOL)doesDrawAsBox	YES if the receiver draws only its bounding box
	getBounds:(NXRect *)boundingRect	Returns the rectangle representing the receiver's
	inCamera:theCamera	bounding box in the coordinates of the camera

Converting Points

	convertObjectPoints:(RtPoint *)points	Converts points from the receiver's coordinate system
	count:(int)n	to that of camera
	toCamera:camera
	convertPoints:(RtPoint *)points	Converts points from an ancestor's coordinate system
	count:(int)n	to that of the receiver
	fromAncestor:(N3DShape *)theShape
	convertPoints:(RtPoint *)points	Converts points from the receiver's coordinate system
	count:(int)n	to that of an ancestor
	toAncestor:(N3DShape *)theShape

Selectability

	setSelectable:(BOOL)flag	Sets whether the receiver can be selected
	(BOOL)isSelectable	YES if the receiver can be selected

Visibility

	setVisible:(BOOL)flag	Sets the receiver to render when renderSelf: is invoked
	(BOOL)isVisible	YES if receiver renders when renderSelf: is invoked

Naming Shapes

	setShapeName:(const char *)aName	Sets the name of the shape
	(const char *)shapeName	Returns the name of the shape

Delegate for Rendering

	setRenderDelegate:aShape	Sets the rendering delegate for the receiver
	removeRenderDelegate	Removes and returns the render delegate
	renderDelegate	Returns the render delegate

Transformation Matrices

setTransformMatrix:(RtMatrix)newTransform

Sets the receiver's transformation matrix

	getTransformMatrix:(RtMatrix)transform	Returns the receiver's transformation matrix
	concatTransformMatrix:(RtMatrix)theMatrix	Multiplies the transform matrix with theMatrix,
	premultiply:(BOOL)flag	premultiplying by theMatrix if flag is YES

getCompositeTransformMatrix:(RtMatrix)theMatrix

relativeToAncestor:(N3DShape *)theAncestor

Returns the matrix representing the transformation between theAncestor's space and the receiver's

getInverseCompositeTransformMatrix:(RtMatrix)theMatrix

relativeToAncestor:(N3DShape *)theAncestor

Returns the matrix representing the transformation between the receiver's space and theAncestor's

Rotation, Scaling, Translation

	rotateAngle:(float)ang	Rotates the receiver about its origin and the point
	axis:(RtPoint)referencePoint
	preRotateAngle:(float)angle	Premultiplies the rotation of the receiver about its
	axis:(RtPoint)referencePoint	origin and the point
	scale:(float)xScaleFactor	Scales the receiver
	:(float)yScaleFactor
	:(float)zScaleFactor
	prescale:(float)xScaleFactor	Scales the receiver, premultiplying the transformation
	:(float)yScaleFactor
	:(float)zScaleFactor
	scaleUniformly:(float)scaleFactor	Scales the receiver uniformly in all axes
	prescaleUniformly:(float)scaleFactor	Scales the receiver uniformly in all axes, premuliplying the transformation
	translate:(float)xTranslation	Translates the receiver
	:(float)yTranslation
	:(float)zTranslation
	pretranslate:(float)xTranslation	Translates the receiver, premultiplying the
	:(float)yTranslation	transformation
	:(float)zTranslation

Archiving

	read:(NXTypedStream *)theStream	Reads the camera from the stream
	write:(NXTypedStream *)theStream	Writes the camera to the stream
	awake	Performs additional initialization after unarchiving