Class: TGrafBundle3D

Declaration: Bundles3D.h

Taxonomy Categories:

Member Functions:


Interface Category:

API.

Inherits From:

TAttribute3DState

Inherited By:

None.

Purpose:

A bundle is a collection of attributes that contain imaging information for the rendering device. For instance, a 3-D bundle contains a TColor that describes the base color of a surface, as well as a TShader that describes how this color is altered by conditions such as reflected light or a texture map. A TGrafBundle3D collects together the attributes needed to render a particular 3-D graphic object, just as a TGrafBundle is used for 2-D. The MGraphic3D class associates a TGrafBundle3D with a 3-D geometry, in order to define the attributes needed for rendering the geometry--color, texture map, and so on. A descendant of MGraphic3D can adopt a TGrafBundle3D, reserving the bundle for its exclusive use until it orphans it. An MGraphic3D has only one bundle, and only one MGraphic3D can have the same bundle. However, a TGrafBundle3D is not always encapsulated in an MGraphic3D--TGrafPort uses a bundle directly to render a geometry. The standard attributes contained in a 3-D bundle include the frame pen, inside and outside colors, inside and outside shaders, and texture map transformation matrix. Each of these standard attributes is described by a corresponding class--TShader, TColor, TPen, and TGrafMatrix. The frame pen determines how the object's wire frame is drawn (hairline by default). The inside and outside color attributes determine the object's base color--the color of the surface before any effects are applied by the shaders. A right-hand rule is applied to determine which surface is inside and which is outside. The inside and outside surfaces have separate shaders. These shaders calculate the final color at every location on the surface, taking into account the lighting, the camera position, and the type of shader. For example, a highly reflective surface whose base color is red can actually appear whitish at the location where a light source is directly reflected. Finally, the texture map transformation matrix attribute specifies a TGrafMatrix that is used to map a 2-D texture to the object's surface. (The texture itself, if any, is specified by the shader attribute.) TGrafBundle3D, derived from TAttribute3DState, supplies explicit member functions to retrieve, adopt, and orphan most of its standard attributes. However, some standard attributes do not have corresponding adopt and orphan member functions. These attributes include the drawing operation, shading resolution, shading interpolation, and backface culling. The drawing operation is either kFrame, which draws the geometry as a wire frame; kFill, which means that the bundle attributes are used to color the surfaces; or kFillAndFrame, which draws both the wire frame and the surfaces. The shading quality specifies how frequently the shader calculates a resultant color--a value of kBest means a color is computed for every pixel, a value of kMedium means the calculation is done only for every vertex, and a value of kFast results in color computation only occurring once per polygon. The shading interpolation determines what happens to the pixels in between. If the interpolation is kFlat, the intermediary pixels have the same color as the most recently shaded pixel, whereas if the interpolation is kSmooth, the intermediary pixels have interpolated colors. If backface culling is turned on (as it is by default), the shading and rendering operations ignore any surface that faces away from the camera, making it invisible. As with 2-D bundles, you can add arbitrary attributes by creating your own TGrafAttribute derived classes (although the rendering device might not be able to do anything with these attributes). These nonstandard attributes are referred to as extended attributes. You add them to the bundle with TGrafBundle3D::AdoptGrafAttribute, access them by name with TGrafBundle3D::GetGrafAttribute, and orphan them by name with TGrafBundle3D::OrphanGrafAttribute. To iterate through the extended attributes, use a TGrafBundleIterator3D object, which you access with TGrafBundle3D::CreateBundleIterator.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGrafBundle3D::TGrafBundle3D

  1. TGrafBundle3D ()
  2. TGrafBundle3D (TColor * adoptOutsideColor, TAttributeState :: EDrawOperation =TAttributeState :: kFrame)
  3. TGrafBundle3D (const TAttribute3DState & state)
  4. TGrafBundle3D (const TGrafBundle3D &)

Interface Category:

API.

Purpose:

  1. Default constructor.
  2. Constructor used to set the standard 3-D graphics bundle attributes: the outside color and the drawing operation (frame, fill, or frame and fill).
  3. Constructor used to create a new object, given an object of the parent class.
  4. Copy constructor.

Calling Context:

  1. Called by the stream-in operators. You can also call this constructor directly. The members of the bundle default to their unset condition.
  2. Call this function directly.
  3. Call this function directly.
  4. Called to copy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::~TGrafBundle3D

virtual ~ TGrafBundle3D ()

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: TGrafBundle3D::SetDrawingOperation

virtual void SetDrawingOperation (TAttributeState :: EDrawOperation operation)

Interface Category:

API.

Purpose:

Sets the type of drawing operation held by this bundle. The options are kFrame (the default, used to draw a wire-frame model of the graphic), kFill (used to draw a filled-surface model of the graphic), and kFillAndFrame (used to draw both a wire-frame and a filled-surface model of the graphic).

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: TGrafBundle3D::SetBackfaceCulling

virtual void SetBackfaceCulling ( TAttribute3DState :: EBackfaceCulling isOn)

Interface Category:

API.

Purpose:

Sets the value of the backface culling mode. If backface culling is enabled, the regions of the graphic that are not visible to the camera will not be rendered. This saves time when rendering complex graphics.

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: TGrafBundle3D::SetShadingInterpolation

virtual void SetShadingInterpolation (TAttribute3DState :: EShadingInterpolationMode interpolation)

Interface Category:

API.

Purpose:

Sets the value of the shading interpolation mode. If shading interpolation is set to flat (kFlat) the color of unshaded pixels is the same as the most recently shaded pixel. If the shading interpolation is set to smooth (kColorSmooth) the color of unshaded pixels is determined by interpolating the color of the previously shaded pixel and the pixel to be shaded next. Smooth interpolation gives a better looking image, but takes longer to render.

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: TGrafBundle3D::SetShadingQuality

virtual void SetShadingQuality (TAttribute3DState :: EShadingQuality shadingQuality)

Interface Category:

API.

Purpose:

Sets the shading quality for the graphics bundle. If the shading quality is set to fast (kFast), the shading is performed only at the polygon level. If the quality is set to medium (kMedium), the shading is performed at the vertex level. The best (kBest) method performs shading calculations on a pixel-by-pixel basis, but requires much greater processing time.

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: TGrafBundle3D::AdoptFramePen

virtual void AdoptFramePen (TPen * pen)

Interface Category:

API.

Purpose:

Assumes ownership of the specified TPen, which is used for drawing the wire frame. The old pen held by the bundle is deleted.

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: TGrafBundle3D::AdoptOutsideShader

virtual void AdoptOutsideShader (TShader * outsideShader)

Interface Category:

API.

Purpose:

Assumes ownership of the specified TShader, which is used for shading the outside surface. The old outside shader held by the bundle is deleted.

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: TGrafBundle3D::AdoptInsideShader

virtual void AdoptInsideShader (TShader * insideShader)

Interface Category:

API.

Purpose:

Assumes ownership of the specified TShader, which is used for shading the inside surface. The old inside shader held by the bundle is deleted.

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: TGrafBundle3D::AdoptOutsideColor

virtual void AdoptOutsideColor (TColor * baseColor)

Interface Category:

API.

Purpose:

Assumes ownership of the specified TColor, which is used as the base color for the outside surface. This color is also applied to the wire frame, for path geometries (such as lines and polylines) as well as for surface geometries. The old outside color held by the bundle is deleted.

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: TGrafBundle3D::AdoptInsideColor

virtual void AdoptInsideColor (TColor * baseColor)

Interface Category:

API.

Purpose:

Assumes ownership of the specified TColor, which is used as the base color for the inside surface. The old inside color held by the bundle is deleted.

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: TGrafBundle3D::AdoptTextureMappingMatrix

virtual void AdoptTextureMappingMatrix (TGrafMatrix * matrix)

Interface Category:

API.

Purpose:

Assumes ownership of the specified TGrafMatrix, which is used to map a 2-D texture to the surface. The old texture mapping matrix held by the bundle is deleted.

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: TGrafBundle3D::AdoptGrafAttribute

virtual void AdoptGrafAttribute (TGrafAttribute *)

Interface Category:

API.

Purpose:

Assumes ownership of the specified TGrafAttribute (an extended attribute). Extended attributes are derived classes of TGrafAttribute that you create to handle special attributes of graphics. This TGrafAttribute is added to the list of extended attributes maintained by the bundle.

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: TGrafBundle3D::GetOutsideShader

virtual const TShader * GetOutsideShader () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the TShader used for shading the outside surface.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A const pointer to the TShader used by the bundle as the outside shader.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetInsideShader

virtual const TShader * GetInsideShader () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the TShader used for shading the inside surface.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A constant pointer to the TShader used by the bundle as the outside shader.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetOutsideColor

virtual const TColor * GetOutsideColor () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the TColor used as the base color for the outside surface and the wire frame.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A constant pointer to the TColor used as the outside base color.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetInsideColor

virtual const TColor * GetInsideColor () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the TColor used as the base color for the inside surface.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A constant pointer to the TColor used as the inside base color.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetTextureMappingMatrix

virtual const TGrafMatrix * GetTextureMappingMatrix () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the TGrafMatrix used to map a 2-D texture to the surface.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A constant pointer to the TGrafMatrix used to map a 2-D texture to the surface.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetFramePen

virtual const TPen * GetFramePen () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the TPen that determines the wire frame's pen style (such as hairline or dashed).

Calling Context:

Call this function directly.

Parameters:

Return Value:

A constant pointer to the TPen used as the frame pen by the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetShadingInterpolation

virtual TAttribute3DState::EShadingInterpolationMode GetShadingInterpolation () const

Interface Category:

API.

Purpose:

Returns kFlat if unshaded pixel have the same color as the most recently shaded pixel; kColorSmooth if unshaded pixels have interpolated colors; or NIL if interpolation has not been set.

Calling Context:

Call this function directly.

Parameters:

Return Value:

The EShadingInterpolationMode value of the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetDrawingOperation

virtual TAttributeState::EDrawOperation GetDrawingOperation() const

Interface Category:

API.

Purpose:

Returns the EDrawOperation that determines whether to paint the fill, the frame, or both.

Calling Context:

Call this function directly.

Parameters:

Return Value:

The EDrawingOperation value of the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetShadingQuality

virtual TAttribute3DState :: EShadingQuality GetShadingQuality () const

Interface Category:

API.

Purpose:

Returns the quality level of the shading calculation, or kShadingQualityUnset if it has not been set.

Calling Context:

Call this function directly.

Parameters:

Return Value:

The EShadingQuality value of the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetBackfaceCulling

virtual TAttribute3DState :: EBackfaceCulling GetBackfaceCulling () const

Interface Category:

API.

Purpose:

Returns the enumeration tag that specifies whether the shading and rendering operations should ignore any surface that faces away from the camera. Returns kCullingUnset if backface culling has not been set.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns kCullingOn if backface culling is turned on.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetGrafAttribute

virtual const TGrafAttribute * GetGrafAttribute (const TToken & key) const

Interface Category:

API.

Purpose:

Gets the specified user-defined attribute . Returns NIL if the attribute specified by the name is not found.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A constant pointer to the TGrafAttribute derived class with the given name.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::OrphanOutsideShader

virtual TShader * OrphanOutsideShader ()

Interface Category:

API.

Purpose:

Relinquishes ownership of the TShader used for the outside surface, returning a pointer to the TShader. The outside TShader of the bundle is set to NIL.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A pointer to a TShader that represents the outside shader previously owned by the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::OrphanInsideShader

virtual TShader * OrphanInsideShader ()

Interface Category:

API.

Purpose:

Relinquishes ownership of the TShader used for the inside surface, returning a pointer to the TShader. The outside TShader of the bundle is set to NIL.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A pointer to a TShader that represents the inside shader previously owned by the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::OrphanOutsideColor

virtual TColor * OrphanOutsideColor ()

Interface Category:

API.

Purpose:

Relinquishes ownership of the TColor used for the outside surface and wire frame, returning a pointer to it. The outside TColor of the bundle is set to NIL.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A pointer to a TColor that represents the outside color previously owned by the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::OrphanInsideColor

virtual TColor * OrphanInsideColor ()

Interface Category:

API.

Purpose:

Relinquishes ownership of the TColor used for the inside surface, returning a pointer to it. The inside TColor of the bundle is set to NIL.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A pointer to a TColor that represents the outside color previously owned by the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::OrphanFramePen

virtual TPen * OrphanFramePen ()

Interface Category:

API.

Purpose:

Relinquishes ownership of the TPen used for frames, returning a pointer to it. The frame TPen of the bundle is set to NIL.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A pointer to a TPen that represents the frame pen previously owned by the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::OrphanTextureMappingMatrix

virtual TGrafMatrix * OrphanTextureMappingMatrix ()

Interface Category:

API.

Purpose:

Relinquishes ownership of the TGrafMatrix used to map a 2-D texture to the surface, returning a pointer to the TGrafMatrix. The texture map TGrafMatrix of the bundle is set to NIL.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A pointer to the TGrafMatrix that represents the 2-D texture map previously owned by the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::OrphanGrafAttribute

virtual TGrafAttribute * OrphanGrafAttribute (const TToken & key)

Interface Category:

API.

Purpose:

Relinquishes ownership of the named TGrafAttribute, returning a pointer to it. The named extended attribute is removed from the bundle's internal list of extended attributes.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A pointer to the named TGrafAttribute object that was previously owned by the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::CreateBundleIterator

virtual TGrafBundleIterator3D * CreateBundleIterator ()

Interface Category:

API.

Purpose:

Creates an iterator that accesses the bundle's extended attributes (but not the standard attributes, which are accessed by their own TGrafBundle3D member functions). You are responsible for deleting this iterator after you are done with it.

Calling Context:

Call this function directly.

Parameters:

Return Value:

A pointer to a TGrafBundleIterator3D.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::operator=

TGrafBundle3D & operator =(const TGrafBundle3D & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

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:

None.

Member Function: TGrafBundle3D::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: TGrafBundle3D::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: TGrafBundle3D::OrphanPrimaryDitherHint

virtual TDitherHint * OrphanPrimaryDitherHint ()

Interface Category:

API.

Purpose:

This causes the graphics bundle to orphan its primary dither hint. This is the object used to suggest what form of dithering to use (if the display platform is capable of performing it).

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a pointer to the newly-orphaned TDitherHint. If there is no dither hint defined, a NIL pointer is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::GetPrimaryDitherHint

virtual const TDitherHint * GetPrimaryDitherHint () const

Interface Category:

API.

Purpose:

Returns a pointer to the current dither hint for this graphics bundle.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the pointer to this graphics bundle's primary dither hint.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafBundle3D::AdoptPrimaryDitherHint

virtual void AdoptPrimaryDitherHint (TDitherHint * ditherHint)

Interface Category:

API.

Purpose:

Allows for the adoption of a dither hint object. If a primary dither hint is already associated with this graphics bundle, the old dither hint is deleted and replaced by the new hint.

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.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.