Class: TGrafDevice

Declaration: GrafDevices.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TFrameBuffer TBoundsMakerDevice

Purpose:

TGrafDevice is an abstract base class that provides graphical imaging services. A TGrafDevice implements rendering in a manner specific to a particular category of output device, such as a frame buffer, a PostScript device, or a vector plotter. In the graphics architecture, TGrafDevice occupies a spot one level below TGrafPort (the class that reduces a graphic hierarchy to a sequence of single geometries, each with a fully specified graphic state), and one level above TDisplayDevice (the class that implements device drivers). Given a geometry and a graphics state by the TGrafPort, the TGrafDevice renders the graphic in a way that the output device can understand. It does this by invoking an appropriate rendering pipeline, as determined by each TGrafDevice derived class. The rendering pipeline is a set of objects which act in sequence to convert the modeled geometry into an image for the output device. TGrafDevice and its associated classes are typically used by hardware developers, not application developers. Hardware developers create classes derived from TGrafDevice in order to support new types of output devices. The reusable modules of the graphics device architecture allow you to write new graphics devices without duplicating many parts of the rendering pipeline. By contrast, most application programmers do not use graphics devices directly. They instead use the View system, GrafEdit, or MGraphic derived classes to create and draw graphic objects. However, these parts of the system all use TGrafDevice indirectly. For example, when you call TPolygon::Draw, TPolygon calls TGrafPort::Draw, and TGrafPort calls the appropriate rendering function of TGrafDevice. Often, a TGrafDevice derived class represents a specific physical device such as a display, a printer, or a plotter. TGrafDevices that represent physical devices have a resolution, bounds in world coordinates, and caching support. However, a TGrafDevice can also be used to render graphics into a nonphysical device, such as an offscreen buffer. A derived class can act as a passive iterator that collects together the elements from a sequence of rendering calls. For example, it can collect geometries and transforms; geometries, transforms, and bundles; just the 2-D primitives; just the 3-D primitives; or transforms and lights. TGrafDevice provides a set of member functions whose name begins with Render, such as RenderLine or RenderBox3D. These are typically invoked by a TGrafPort. All of them take a geometry, a TGrafState, and a TGrafDeviceCache as arguments. The TGrafState holds constant state information such as clipping, transformation, scene, and attributes. TGrafDeviceCache allows the device to cache state. The TGrafDevice class itself simply provides the interface protocol for these rendering functions; it is up to the derived class to implement them by feeding data to a particular rendering pipeline. All TGrafDevices are reentrant; they cannot keep global rendering data. Either the TGrafDevice defines data only at the time it is constructed, or it accesses the data on a separate server, or it stores data in a cache passed in to every render call.

Instantiation:

Abstract class; do not allocate.

Deriving Classes:

Provided classes: TFrameBuffer (a device with a pixel buffer), TBundleOverrideGrafDevice (a device with its own bundle), TGrafCluster (a collection of TGrafDevices), and several classes not in the graphics subsystem (such as some printing classes). The most important physical device is the desktop device, which includes one or more screen devices derived from both TScreenDevice and TGrafDevice. The Video framework creates the desktop device, and passes it to the user through the window server and the view system. Derived classes should override the Render member functions to perform the desired type of rendering. Classes representing physical devices should set the bounds and resolution.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGrafDevice::TGrafDevice

  1. TGrafDevice (const TGRect & worldbounds)
  2. TGrafDevice (const TGrafDevice &)
  3. TGrafDevice ()

Interface Category:

API.

Purpose:

  1. Sets the bounds to the specified value in world coordinates.
  2. Copy constructor.
  3. Default constructor. Sets the bounds to infinity.

Calling Context:

  1. Called to create a device with a specific bounding rectangle.
  2. Called to copy an object.
  3. Called by the stream-in operators and the default constructor of derived classes.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::~TGrafDevice

virtual ~ TGrafDevice ()

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: TGrafDevice::RenderLine

virtual void RenderLine (const TGLine & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified line using the specified grafstate. For instance, a rendering device renders the line according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderPolyline

virtual void RenderPolyline (const TGPolyline & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified polyline using the specified grafstate. For instance, a rendering device renders the polyline according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderCurve

virtual void RenderCurve (const TGCurve & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified curve using the specified grafstate. For instance, a rendering device renders the curve according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderRect

virtual void RenderRect (const TGRect & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified rectangle using the specified grafstate. For instance, a rendering device renders the rectangle according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderEllipse

virtual void RenderEllipse (const TGEllipse & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified ellipse using the specified grafstate. For instance, a rendering device renders the ellipse according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderPolygon

virtual void RenderPolygon (const TGPolygon & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified polygon using the specified grafstate. For instance, a rendering device renders the polygon according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderLoop

virtual void RenderLoop (const TGLoop & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified loop using the specified grafstate. For instance, a rendering device renders the loop according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderArea

virtual void RenderArea (const TGArea & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified area using the specified grafstate. For instance, a rendering device renders the area according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderGlyphRun

virtual void RenderGlyphRun (const TGGlyphRun & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified glyph run using the specified grafstate. For instance, a rendering device renders the glyph run according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderImage

virtual void RenderImage (const TGImage & image, const TGRect & source, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified image using the specified grafstate. For instance, a rendering device renders the image according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderLine3D

virtual void RenderLine3D (const TGLine3D & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified 3-D line using the specified grafstate. For instance, a rendering device renders the 3-D line according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderPolyline3D

virtual void RenderPolyline3D (const TGPolyline3D & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified 3-D polyline using the specified grafstate. For instance, a rendering device renders the 3-D polyline according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderCurve3D

virtual void RenderCurve3D (const TGCurve3D & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified 3-D curve using the specified grafstate. For instance, a rendering device renders the 3-D curve according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderSampledSurface3D

virtual void RenderSampledSurface3D (const TSampledSurface3D & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified 3-D sampled surface using the specified grafstate. For instance, a rendering device renders the 3-D sampled surface according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderSurface3D

virtual void RenderSurface3D (const TGSurface3D & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified 3-D surface using the specified grafstate. For instance, a rendering device renders the 3-D surface according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::RenderBox3D

virtual void RenderBox3D (const TGBox3D & geometry, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Processes the specified 3-D box using the specified grafstate. For instance, a rendering device renders the 3-D box according to the settings in the grafstate. The device cache is used by multithread-safe devices for storing data from one call to the next.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::EndFrame

virtual void EndFrame (const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Signifies the end of a 3-D frame. Call this function when all the elements of a 3-D picture are sent to the device so the device can process them.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::GetWorldBounds

virtual TGRect GetWorldBounds () const

Interface Category:

API.

Purpose:

Returns the bounding rectangle of the device in world coordinates.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the bounding rectangle of the device in world coordinates.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The bounding rectangle can be the infinite rectangle for some devices.

Member Function: TGrafDevice::GetTimeStamp

virtual TPseudoTimeStamp GetTimeStamp () const

Interface Category:

API.

Purpose:

Returns the time stamp of the device. All devices in an address space are guaranteed to have unique time stamps.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the time stamp of the device.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::CreateDeviceCache

virtual TGrafDeviceCache * CreateDeviceCache () const

Interface Category:

API.

Purpose:

Returns a heap-allocated object that is passed in when a call is made to the render calls. This object is owned by the caller.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a pointer to a heap-allocated device cache object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller owns the device cache and must delete it when it is no longer needed. The device cache is valid as long as the device exists.

Member Function: TGrafDevice::CreateGrafResolution

virtual TGrafMatrix * CreateGrafResolution (const TGRect & areaOfInterest =TGRect :: kInfiniteRect) const

Interface Category:

API.

Purpose:

Returns a matrix that contains the device transform; in other words, the transformation from world coordinates to device coordinates. The rectangular area of interest is used as a guide to choose the most applicable device in the case of multiple devices. The very nature of this function is flawed because there can be more than one underlying graphics device, each with a different resolution. Thus, the value returned might not apply to the device as a whole. Therefore, use of this function is not recommended because it can produce unexpected results.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the device matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use of this function is not recommended due to its imprecise nature.

Member Function: TGrafDevice::Flush

virtual void Flush ()

Interface Category:

API.

Purpose:

Causes the graphics device to process all the graphic elements that it has received and return them when it is finished. Use it for synchronization of the graphics with the thread that is drawing the graphics. For example, an object that controls a scrollbar should call this function to ensure that it doesn't get ahead of the graphics, which could result in a negative user experience.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::operator>>=

virtual 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: TGrafDevice::operator<<=

virtual 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.

Member Function: TGrafDevice::UpdateTimeStamp

virtual void UpdateTimeStamp ()

Interface Category:

API.

Purpose:

Updates the time stamp of the device to a new unique value. Call this function when a device changes in some visible way, such as when its size changes.

Calling Context:

Call this function from derived classes.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::SetWorldBounds

virtual void SetWorldBounds (const TGRect & newBounds)

Interface Category:

API.

Purpose:

Sets the bounding rectangle of the device in world coordinates. This value is returned from GetWorldBounds by default.

Calling Context:

Call this function from derived classes.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::ScrollArea

virtual void ScrollArea (const TGArea & source, const TGPoint & translation, TGArea & invalidArea, const TGrafState & grafState, TGrafDeviceCache & cache)

Interface Category:

API.

Purpose:

Tells the device to move the contents of the specified area the specified amount and return the damaged area (the area that needs to be cleaned up). This is the interface to bit-blits of areas on a frame buffer device. A TGrafDevice derived class that cannot handle this operation returns without doing anything. The default implementation of ScrollArea does this. The source area is passed in as sourceArea. The destination area is passed in as destArea. DestArea is modified to contain the damaged area, which is returned to the caller.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::GetWorldArea

virtual TGArea GetWorldArea () const

Interface Category:

API.

Purpose:

Returns the area that defines the boundary of the device in world coordinates.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the boundary area of the device in world coordinates.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafDevice::SetBackBufferID

void SetBackBufferID (TPseudoTimeStamp &)

Interface Category:

API.

Purpose:

Sets the back buffer ID of the device to the specified value. Developers should not use this function.

Calling Context:

Called internally.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function should be treated as internal.

Member Function: TGrafDevice::UpdateBackBufferID

void UpdateBackBufferID ()

Interface Category:

API.

Purpose:

Updates the value of the back buffer ID of the device to the next available unique value.

Calling Context:

Called internally.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function should be treated as internal.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.