Class: TGrafPort

Declaration: GrafPort.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TLinkedGrafPort TRootGrafPort

Purpose:

TGrafPort is an abstract class that represents a port, one of the central objects of the Graphics system. Graphics are drawn to a port, which in turn invokes the rendering operations of a particular device. A port has knowledge of two key pieces of information: (1) the graphic state, as represented by a TGrafState, and (2) the rendering device (represented by a TGrafDevice and its associated TGrafDeviceCache). TGrafPort owns a TGrafState, which specifies all the state variables need to draw a geometry. These include 2-D attributes (paint, frame style, transfer mode, and so on), 2-D view and model transformation matrices, the 2-D clipping area, 3-D per-object attributes (such as shaders and colors), 3-D scene attributes (such as lights and camera), and the 3-D model transformation matrix. TGrafPort also has access to TGrafDevice, along with a device cache. The device is specified by a constructor argument in concrete descendants of TGrafPort. It is accessed by TGrafPort::GetDevice. GetDevice can be overridden to cause rendering to occur on a different device. For instance, back-buffering of a graphic can be implemented by overriding GetDevice to return an off-screen device instead of the screen. In order to be rendered on a device, a graphics object such as an MGraphic must describe itself in terms of the basic geometries of which it is composed. TGrafPort::Draw allows a graphic object to conveniently convey its contents, via the port, to a TGrafDevice object for rendering. TGrafPort provides a good many versions of TGrafPort::Draw, each overloaded with a different set of arguments. These are non-virtual convenience functions, implemented in TGrafPort. Each invokes the corresponding TGrafDevice rendering function. For example, TGrafPort::Draw(TGLine) invokes TGrafDevice::RenderLine(TGLine,TGrafState,TGrafDeviceCache). TGrafPort passes its graphic state and its device cache in the latter two arguments, so that the device can access all the state variables needed to draw the geometry. For convenience, TGrafPort provides versions of Draw that take an attribute state and a model matrix as additional arguments. These arguments override the existing state. Graphics are frequently arranged in hierarchies. This requires the child graphic's port to be linked to the parent graphic's port, concatenating the graphic state. TGrafPort itself provides no protocol for hierarchies; such behavior is provided by derived classes.

Instantiation:

Abstract class; do not allocate.

Deriving Classes:

Derived classes should not override the overloaded Draw member functions, because they simply invoke the corresponding TGrafDevice member functions.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

Developers should treat the version enum of this class as private.

Member Function: TGrafPort::~TGrafPort

virtual ~ TGrafPort ()

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.

Member Function: TGrafPort::GetDevice

virtual TGrafDevice * GetDevice ()

Interface Category:

API.

Purpose:

Returns a pointer to the TGrafDevice to which this port draws its graphics.

Calling Context:

Clients shouldn't need to call it directly except in rare cases.

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:

This is a pure virtual function that must be overridden by the derived classes.

Member Function: TGrafPort::GetCache

virtual TGrafDeviceCache * GetCache ()

Interface Category:

API.

Purpose:

Returns a pointer to the TGrafDeviceCache associated with the device.

Calling Context:

Clients shouldn't need to call it directly except in very rare cases.

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:

This is a pure virtual function that must be overridden by the derived classes.

Member Function: TGrafPort::GetState

virtual const TGrafState * GetState () const

Interface Category:

API.

Purpose:

Returns a pointer to a TGrafState object that represents the 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 constant pointer to the concatenated graphic state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use the TGrafStateAccessor class to get access to the grafstate in the port. This is a pure virtual function that must be overridden by derived classes.

Member Function: TGrafPort::UseState

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 TGrafPort:::DoneWithState is called. TGrafPort::UseState is used by TGrafPort classes implemented by the View system; it grabs a semaphore in UseState and releases it in DoneWithState to protect the grafstate from being changed (for example, moving the view) while drawing takes place.

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:

None.

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 the derived classes.

Member Function: TGrafPort::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. This is used by TGrafPort classes implemented by the View system; it grabs a semaphore in UseState and releases it in DoneWithState to protect the grafstate from being changed (for example, moving the view) while drawing takes place.

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:

None.

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 the derived classes.

Member Function: TGrafPort::GetPortForRegisteringStateUsage

virtual const TGrafPort* GetPortForRegisteringStateUsage () const

Interface Category:

API.

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.

Member Function: TGrafPort::Draw

  1. void Draw (const TGLine & geometry)
  2. void Draw (const TGPolyline & geometry)
  3. void Draw (const TGCurve & geometry)
  4. void Draw (const TGRect & geometry)
  5. void Draw (const TGEllipse & geometry)
  6. void Draw (const TGPolygon & geometry)
  7. void Draw (const TGLoop & geometry)
  8. void Draw (const TGArea & geometry)
  9. void Draw (const TGGlyphRun & geometry)
  10. void Draw (const TGImage & theImage, const TGRect & srcBounds)
  11. void Draw (const TGLine3D & geometry)
  12. void Draw (const TGPolyline3D & geometry)
  13. void Draw (const TGCurve3D & geometry)
  14. void Draw (const TGSurface3D & geometry)
  15. void Draw (const TSampledSurface3D & geometry)
  16. void Draw (const TGBox3D & geometry)
  17. void Draw (const TGLine & geometry, const TAttributeState & attributeState, const TGrafMatrix & modelMatrix =TGrafMatrix :: GetIdentity ())
  18. void Draw (const TGPolyline & geometry, const TAttributeState & attributeState, const TGrafMatrix & modelMatrix =TGrafMatrix :: GetIdentity ())
  19. void Draw (const TGCurve & geometry, const TAttributeState & attributeState, const TGrafMatrix & modelMatrix =TGrafMatrix :: GetIdentity ())
  20. void Draw (const TGRect & geometry, const TAttributeState & attributeState, const TGrafMatrix & modelMatrix =TGrafMatrix :: GetIdentity ())
  21. void Draw (const TGEllipse & geometry, const TAttributeState & attributeState, const TGrafMatrix & modelMatrix =TGrafMatrix :: GetIdentity ())
  22. void Draw (const TGPolygon & geometry, const TAttributeState & attributeState, const TGrafMatrix & modelMatrix =TGrafMatrix :: GetIdentity ())
  23. void Draw (const TGLoop & geometry, const TAttributeState & attributeState, const TGrafMatrix & modelMatrix =TGrafMatrix :: GetIdentity ())
  24. void Draw (const TGArea & geometry, const TAttributeState & attributeState, const TGrafMatrix & modelMatrix =TGrafMatrix :: GetIdentity ())
  25. void Draw (const TGGlyphRun & geometry, const TAttributeState & attributeState, const TGrafMatrix & modelMatrix =TGrafMatrix :: GetIdentity ())
  26. void Draw (const TGImage & theImage, const TGRect & srcBounds, const TAttributeState & attributeState, const TGrafMatrix & modelMatrix =TGrafMatrix :: GetIdentity ())
  27. void Draw (const TGLine3D & geometry, const TAttribute3DState & attributeState, const TGrafMatrix3D & modelMatrix =TGrafMatrix3D :: GetIdentity ())
  28. void Draw (const TGPolyline3D & geometry, const TAttribute3DState & attributeState, const TGrafMatrix3D & modelMatrix =TGrafMatrix3D :: GetIdentity ())
  29. void Draw (const TGCurve3D & geometry, const TAttribute3DState & attributeState, const TGrafMatrix3D & modelMatrix =TGrafMatrix3D :: GetIdentity ())
  30. void Draw (const TGSurface3D & geometry, const TAttribute3DState & attributeState, const TGrafMatrix3D & modelMatrix =TGrafMatrix3D :: GetIdentity ())
  31. void Draw (const TSampledSurface3D & geometry, const TAttribute3DState & attributeState, const TGrafMatrix3D & modelMatrix =TGrafMatrix3D :: GetIdentity ())
  32. void Draw (const TGBox3D & geometry, const TAttribute3DState & attributeState, const TGrafMatrix3D & modelMatrix =TGrafMatrix3D :: GetIdentity ())

Interface Category:

API.

Purpose:

  1. Renders the given geometry object (TGLine) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  2. Renders the given geometry object (TGPolyline) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  3. Renders the given geometry object (TGCurve) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  4. Renders the given geometry object (TGRect) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  5. Renders the given geometry object (TGEllipse) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  6. Renders the given geometry object (TGPolygon) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  7. Renders the given geometry object (TGLoop) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  8. Renders the given geometry object (TGArea) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  9. Renders the given geometry object (TGGlyphRun) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  10. Renders the given geometry object (TGImage) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  11. Renders the given geometry object (TGLine3D) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  12. Renders the given geometry object (TGPolyline3D) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  13. Renders the given geometry object (TGCurve3D) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  14. Renders the given geometry object (TGSurface3D) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  15. Renders the given geometry object (TGSampleSurface3D) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  16. Renders the given geometry object (TGBox3D) on the graphics device specified by this TGrafPort object. This is a non-virtual convenience function and thus cannot be overridden.
  17. Renders the given geometry object (TGLine) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  18. Renders the given geometry object (TGPolyline) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  19. Renders the given geometry object (TGCurve) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  20. Renders the given geometry object (TGRect) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  21. Renders the given geometry object (TGEllipse) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  22. Renders the given geometry object (TGPolygon) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  23. Renders the given geometry object (TGLoop) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  24. Renders the given geometry object (TGArea) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  25. Renders the given geometry object (TGGlyphRun) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  26. Renders the given geometry object (TGImage) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  27. Renders the given geometry object (TGLine3D) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  28. Renders the given geometry object (TGPolyLine3D) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  29. Renders the given geometry object (TGCurve3D) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  30. Renders the given geometry object (TGSurface3D) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  31. Renders the given geometry object (TGSampleSurface3D) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.
  32. Renders the given geometry object (TGBox3D) on the graphics device specified by this TGrafPort object. The given attribute state and model matrix are concatenated with the attribute state and model matrix of this TGrafPort and used by the device for the duration of the call. Use of this call is not recommended if more than one call is made using the same attribute state or matrix because the concatenation takes place each time the call is made. For greater efficiency, use linked graph ports instead. This is a non-virtual convenience function and thus cannot be overridden.

Calling Context:

  1. Call this function directly from a concrete derived class.
  2. Call this function directly from a concrete derived class.
  3. Call this function directly from a concrete derived class.
  4. Call this function directly from a concrete derived class.
  5. Call this function directly from a concrete derived class.
  6. Call this function directly from a concrete derived class.
  7. Call this function directly from a concrete derived class.
  8. Call this function directly from a concrete derived class.
  9. Call this function directly from a concrete derived class.
  10. Call this function directly from a concrete derived class.
  11. Call this function directly from a concrete derived class.
  12. Call this function directly from a concrete derived class.
  13. Call this function directly from a concrete derived class.
  14. Call this function directly from a concrete derived class.
  15. Call this function directly from a concrete derived class.
  16. Call this function directly from a concrete derived class.
  17. Call this function directly from a concrete derived class.
  18. Call this function directly from a concrete derived class.
  19. Call this function directly from a concrete derived class.
  20. Call this function directly from a concrete derived class.
  21. Call this function directly from a concrete derived class.
  22. Call this function directly from a concrete derived class.
  23. Call this function directly from a concrete derived class.
  24. Call this function directly from a concrete derived class.
  25. Call this function directly from a concrete derived class.
  26. Call this function directly from a concrete derived class.
  27. Call this function directly from a concrete derived class.
  28. Call this function directly from a concrete derived class.
  29. Call this function directly from a concrete derived class.
  30. Call this function directly from a concrete derived class.
  31. Call this function directly from a concrete derived class.
  32. Call this function directly from a concrete derived class.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Do not override these classes.

Member Function: TGrafPort::EndFrame

void EndFrame ()

Interface Category:

API.

Purpose:

Indicates the end of a 3-D scene to the renderer, so that subsequent drawing goes to a new scene. Call this function after calling any of the Draw functions.

Calling Context:

Call this function directly from a concrete derived class.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafPort::TGrafPort

  1. TGrafPort ()
  2. TGrafPort (const TGrafPort &)

Interface Category:

API.

Purpose:

  1. Default constructor. This is a protected constructor that must be overridden by the derived classes.
  2. Copy constructor. This is a protected constructor that must be overridden by the derived classes.

Calling Context:

  1. Called by the stream-in operators. Do not call this function directly.
  2. Called to copy an object. Do not call this function directly, except from within the copy constructor of a derived class.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafPort::operator=

TGrafPort & operator =(const TGrafPort & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Do not call this function directly.

Parameters:

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a protected member function that is designed to be overridden by the derived classes.

Member Function: TGrafPort::operator>>=

TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafPort::operator<<=

TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.