Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TGrafPort
Inherited By:
TLinkedBundle3DPort
TLinkedBundlePort
TLinkedClipPort
TLinkedModelMatrix3DPort
TLinkedModelMatrixPort
TLinkedScenePort
TLinkedViewMatrixPort
Purpose:
TLinkedGrafPort is an abstract class derived from TGrafPort. It provides the basic functionality for linked ports. Think of a linked port as a semantic copy of another port (the parent port), with one or more changes made to the copy. It is called a linked port because of the efficient mechanism used to achieve this result. Because it is much too slow to actually make a copy of the parent port, the linked port stores a pointer to the parent and only changes those portions of the graphic state that are different from the parent port's graphic state. (The derived classes achieve this result by internally using linked state objects, such as TLinkedAttributeGrafState.) Thus, linked ports are very lightweight; they are meant to be created and deleted as needed.
A port is linked to a parent port through the TLinkedGrafPort constructor, which takes the parent port as an argument. Using linked ports is very simple. For example, if a graphic has a model matrix that it needs to concatenate with that of its parent graphic, it can use a TLinkedModelMatrixPort. The graphic object's implementation creates the linked port, passing in the parent port and the desired model matrix as constructor arguments. The TLinkedModelMatrixPort constructor then arranges for this new port to contain the same state as the parent, with the exception of the model matrix.
Instantiation:
Abstract class; do not allocate.
Deriving Classes:
Provided classes: TLinkedBundlePort, TLinkedBundle3DPort, TLinkedAttributePort, TLinkedAttribute3DPort, TLinkedViewMatrixPort, TLinkedModelMatrixPort, TLinkedModelMatrix3DPort, TLinkedClipPort, and TLinkedScenePort.
The default behavior for a TLinkedGrafPort is to use all the parent port's graphic state. TLinkedGrafPort::UseState and TLinkedGrafPort::DoneWithState simply invoke the parent port's UseState and DoneWithState functions. Similarly, the GetDevice and GetCache functions return the parent port's device and cache by default. GetState, however, must be overridden.
Derived classes typically use their constructors to specify the parts of the graphic state that are different from the parent port. For example, the TLinkedModelMatrix3DPort constructors take a TGrafMatrix3D or TLinkableMatrix3DState argument, using these to create a new graphic state in which the model matrix state is concatenated with that of the parent. Typically, derived classes leave the default constructor, copy constructor, and assignment operator unimplemented.
Concurrency:
Not multithread safe.
Resource Use:
Because a linked port references objects supplied by the parent port, the parent must exist as long as the child port exists. This can be ensured by always creating linked ports as local variables within a stack frame.
Objects are often passed into the constructors of linked ports by pointer, which implies that the port retains the pointer for subsequent access to the object. This means that if the pointed-to object can change during the lifetime of the port, the linked port must stay up to date with the pointed-to object, reflecting any changes.
virtual ~ TLinkedGrafPort ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual TGrafDevice * GetDevice ()
Interface Category:
API.
Purpose:
Returns a pointer to the TGrafDevice to which this port draws its graphics. It always returns the parent's device.
Calling Context:
Do not call this function directly. However, this function is designed to be called from derived classes that inherit the function without overriding the definition.
Parameters:
Return Value:
Returns a pointer to the TGrafDevice to which this port draws its graphics.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual TGrafDeviceCache * GetCache ()
Interface Category:
API.
Purpose:
Returns a pointer to the TGrafDeviceCache associated with the device. It always returns the parent's device.
Calling Context:
Do not call this function directly. However, this function is designed to be called from derived classes that inherit the function without overriding the definition.
Parameters:
Return Value:
Returns a pointer to the TGrafDeviceCache associated with the device.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual const TGrafState * GetState () const
Interface Category:
API.
Purpose:
Returns a pointer to a TGrafState object that represents the concatenated graphic state of this object.
Calling Context:
Do not call this function directly. This function is designed to be called by internal classes of the Graphics system (most notably, TGrafStateAccessor).
Parameters:
Return Value:
Returns a pointer to a TGrafState object that represents the graphics state of this object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This is a pure virtual function that must be overridden by derived classes.
virtual void UseState () const
Interface Category:
API.
Purpose:
Marks the graphic state as being in use so that no changes to the state are made until the DoneWithState function is called.
Calling Context:
Do not call this function directly. This class is designed to be used by the Graphics system (most notably, TGrafStateAccessor).
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLinkedGrafPort::DoneWithState
virtual void DoneWithState () const
Interface Category:
API.
Purpose:
Marks the graphic state as being no longer in use so that changes to the state can be made.
Calling Context:
Do not call this function directly. This class is designed to be used by the Graphics system (most notably, TGrafStateAccessor).
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
TLinkedGrafPort (TGrafPort * parent)
Interface Category:
API.
Purpose:
Constructor. Makes the given TGrafPort object the parent of this object.
Calling Context:
Do not call this function directly.
Parameters:
- TGrafPort * parent -The graph port to use as the parent.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This is a protected constructor that is designed to be called only from constructors of derived classes.
const TGrafPort * GetParent () const
Interface Category:
API.
Purpose:
Returns a pointer to the parent TGrafPort object.
Calling Context:
Call from a derived class to get a pointer to the parent TGrafPort object.
Parameters:
Return Value:
Returns a pointer to the parent TGrafPort object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLinkedGrafPort::GetPortForRegisteringStateUsage
virtual const TGrafPort * GetPortForRegisteringStateUsage () const
Interface Category:
Not multithread safe.
Purpose:
Provides a more efficient way to get access to the port that needs to have its usage registered. Can result in faster state usage registering for linked port objects. Returns this object as a default value.
Calling Context:
Do not call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Deriving classes must override this function.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.