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

N3DContextManager

	Inherits From:	Object
	Declared In:	3Dkit/N3DContextManager.h

Class Description

N3DContextManager creates and manages the Interactive RenderMan contexts for all applications using the 3D Graphics Kit. It establishes an application's main connection to the Interactive RenderMan renderer in the Window Server, and releases it when done.  It also establishes and releases other interactive rendering contexts on request. You will rarely need to use this class directly.  The 3D Kit--through N3DCamera and N3DImageRep--establishes contexts for interactive rendering as needed. A context is the portion of a RenderMan program contained within the RiBegin() and RiEnd() calls.  Thus, each time a new context is created, an RiBegin() function call is sent to the Interactive RenderMan renderer.  Each time a context is destroyed, an RiEnd() function call is sent. An application has only one N3DContextManager object and only one main context.  The main context is the context by which the application usually interacts with the Interactive RenderMan renderer.  An application's context manager is instantiated and the main context is created the first time an N3DCamera is instantiated.  You can get the main context at any time, whether or not it existed previously, with the message:

[[N3DContextManager new] mainContext]

You can create additional contexts for other purposes--for example, for printing or saving RIB output from the program in a file. Each new context created this way is entered into a HashTable of contexts used by the application.  You refer to contexts using the token returned by one of the create...  methods, or using the name passed to one of those methods. Interactive RenderMan provides for switching between multiple execution contexts with the RiContext() function.  Each time the context is set with one of the N3DContextManager methods, an RiContext() call is sent to the renderer.

Instance Variables

RtToken mainContext; id contextTable; RtToken currentContext;

	mainContext	Main context
	contextTable	Hash table of contexts
	currentContext	Currently selected context

Method Types

Initializing and freeing

+ new

free

	Getting the main context	mainContext
	Creating other contexts	createContext:

createContext:withRenderer: createContext:toFile:

Managing the current context

currentContext

setCurrentContext: setCurrentContextByName:

Destroying a context

destroyContext:

destroyContextByName:

Archiving

awake

read: write:

Class Methods

new

+ new

Creates, if necessary, and returns the N3DContextManager for an application.  Each application has one and only one N3DContextManager instance, which handles creating, switching, and destroying all Interactive RenderMan contexts for an application.

Instance Methods

awake

awake

Initializes the receiver, a newly unarchived instance of N3DContextManager.

createContext:

(RtToken)createContext:(const char *)contextName

Creates and returns the token for a new Interactive RenderMan context with the name contextName.  The new context is entered into the Interactive RenderMan context dictionary and made the current context.  This method works by invoking createContext:withRenderer: with RI_DRAFT as the renderer argument.  If a new context cannot be created for any reason, RI_NULL is returned and the current context remains as before. See also:  createContext:withRenderer:, createContext:toFile:

createContext:toFile:

(RtToken)createContext:(const char *)contextName

toFile:(const char *)ribFile

Creates and returns the token for an archiving context with the name contextName.  The new context is created and entered into the Interactive RenderMan context dictionary.  If you pass a null pointer as contextName, a unique string is created for the context name. ribFile should be a full pathname, including a ".rib" extension.  If ribFile doesn't exist, it is created; if ribFile does exist, it is overwritten.  If ribFile is NULL, the context will be opened on a file ri.rib in the application's executable file directory. When a context is created with this method, making it the current context causes the Interactive RenderMan renderer to send subsequent RIB code from the application to the file ribFile. If a new context cannot be created for any reason, RI_NULL is returned. See also:  createContext:, createContext:withRenderer:

createContext:toStream:

Does nothing, returns NULL.  This method is not implemented for NEXTSTEP Release 3. See also:  createContext:, createContext:withRenderer:, createContext:toFile:

createContext:withRenderer:

(RtToken)createContext:(const char *)contextName withRenderer:(RtToken)renderer

Creates and returns the token for a new Interactive RenderMan context with the name contextName.  The new context is entered into the Interactive RenderMan contexts dictionary and made the current context.  If you pass a null pointer as contextName, a unique string is created for the context name.  If a new context cannot be created for any reason, RI_NULL is returned and the current context remains as before. renderer can be RI_DRAFT or RI_ARCHIVE.  The RI_DRAFT renderer is used to display interactive rendering; you can create an RI_DRAFT context using the createContext: method.  The RI_ARCHIVE renderer is used to archive RIB code; you can create an RI_ARCHIVE context using the method createContext:toFile:. See also:  createContext:, createContext:toFile:

currentContext

(RtToken)currentContext

Returns the token for the current Interactive RenderMan context.

destroyContext:

(void)destroyContext:(RtToken)aContext

Destroys aContext by making it the current Interactive RenderMan context, sending an RiEnd() function call to the Interactive RenderMan renderer, then removing aContext from the N3DContextManager's context table.  If aContext was the current context, the current context is set to NULL.  If another context was the current context, it's reset as the current context. See also:  createContext:, createContest:toFile:, createContext:withRenderer:

destroyContextByName:

(void)destroyContextByName:(const char *)contextName

Destroys the Interactive RenderMan context referred to by contextName by making it the current Interactive RenderMan context, sending an RiEnd() function call to the Interactive RenderMan renderer, then removing contextName from the N3DContextManager's context table.  If the destroyed context was the current context, current context is set to NULL.  If another context was the current context, it is reset as the current context. See also:  createContext:, createContest:toFile:, createContext:withRenderer:

free

free

Frees the receiving N3DContextManager after destroying all Interactive RenderMan contexts the manager has created. Returns nil.

mainContext

(RtToken)mainContext

Returns the token for the main Interactive RenderMan context.  If the main context doesn't exist yet, this method creates it and makes it the current context.

read:

read:(NXTypedStream *)stream

Reads the receiver from the typed stream stream.  Returns self. See also:  awake, write:

setCurrentContext:

(RtToken)setCurrentContext:(RtToken)aContext

Sets the current Interactive RenderMan context to be aContext (if that context is valid).  Returns the token for the former current context.

setCurrentContextByName:

(RtToken)setCurrentContextByName:(const char *)contextName

Sets the current Interactive RenderMan context to be the context named contextName (if it is a valid context).  Returns the token for the former current context.

write:

write:(NXTypedStream *)stream

Writes the receiver to the typed stream stream.  Returns self. See also:  awake, read: