Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members | Related Pages | Examples

DWFToolkit::DWFModel Class Reference
[3D Publisher API]

#include "dwf/publisher/model/Model.h"

Inheritance diagram for DWFToolkit::DWFModel:

Inheritance graph
[legend]
Collaboration diagram for DWFToolkit::DWFModel:

Collaboration graph
[legend]
List of all members.

Detailed Description

A publishable object that represents a single EModel DWF section.
Since:
7.0.1.

This class unifies the publication of EModel section graphics and metadata. The model is used to to simulataneouly capture the final scene graph and the object and property definitions and relationships to objects in the scene. This implementation is intended to work well for large source databases where keeping the entire scene graph in memory is prohibitively slow or physically contrained by system resoures. As such, the graphics are streamed to disk as they are acquired. The structural relationships, however, are captured in memory for delayed examination and association. This allows publishers the most flexibility in processing the data.

Examples:

3DPublish/3DPublish_UTF8.cpp.

Definition at line 66 of file Model.h.

Public Types

enum  tePolygonHandedness
 The winding order of the vertices of polygon or shell face(s). This setting is critical for correctly surface and face shading and culling.

Public Member Functions

_DWFTK_API DWFModel (DWFOutputStream &rModelStream, const DWFString &zModelTitle="", const DWFString &zModelSource="", const DWFString &zModelSourceID="") throw ()
_DWFTK_API DWFModel (const DWFString &zModelTitle="", const DWFString &zModelSource="", const DWFString &zModelSourceID="") throw ()
_DWFTK_API ~DWFModel () throw ()
_DWFTK_API void open (tePolygonHandedness ePolygonHandedness, DWFUnits::teType eModelUnits, double *pTransform=NULL, bool bUseDefaultLighting=true, bool bUsePublishedEdges=false, bool bUseSilhouetteEdges=false) throw ( DWFException )
_DWFTK_API void close () throw ( DWFException )
_DWFTK_API void enableW3DCompression (bool bEnableStreamCompression=true, bool bEnableConnectivityCompression=true, bool bEnableGlobalQuantizationCompression=false) throw ( DWFException )
_DWFTK_API void enableNormalsCompression (char nTotalNormalBits=keNormal_DefaultResolution) throw ()
_DWFTK_API void enableVertexCompression (char nTotalVertexBits=keVertex_DefaultResolution, char nTotalParameterBits=keTextureParameter_FullResolution) throw ()
_DWFTK_API void disableAllCompression () throw ( DWFException )
_DWFTK_API void publish (DWFPublisher &rPublisher) throw ( DWFException )
_DWFTK_API DWFSegment openSegment () throw ( DWFException )
_DWFTK_API DWFIncludeSegment openIncludeSegment () throw ( DWFException )
_DWFTK_API DWFStyleSegment openStyleSegment () throw ( DWFException )
_DWFTK_API void createView (const char *zName, W3DCamera &rViewCamera) throw ( DWFException )
_DWFTK_API void setBoundingCube (float nMinX, float nMinY, float nMinZ, float nMaxX, float nMaxY, float nMaxZ) throw ( DWFException )
_DWFTK_API void setBoundingSphere (float nCenterX, float nCenterY, float nCenterZ, float nRadius) throw ( DWFException )
_DWFTK_API void setEdgeColor (float anRGB[3]) throw ()
_DWFTK_API const DWFStringgetModelTitle () const throw ()
_DWFTK_API const DWFStringgetModelSource () const throw ()
_DWFTK_API const DWFStringgetModelSourceID () const throw ()
_DWFTK_API const W3DCameragetDefaultView () const throw ()
_DWFTK_API void getBoundingVolume (vector< double > &rBounds) const throw ()
_DWFTK_API bool useModelLighting () const throw ()
_DWFTK_API bool useSilhouetteEdges () const throw ()
_DWFTK_API const float *const getEdgeColor () const throw ()
_DWFTK_API DWFUnits::teType getUnits () const throw ()
_DWFTK_API void getTransform (double *pTransform) const throw ()
_DWFTK_API tePolygonHandedness getPolygonHandedness () const throw ()
_DWFTK_API const DWFStringgetMIMEType () throw ( DWFException )
_DWFTK_API DWFInputStreamgetInputStream () throw ( DWFException )
_DWFTK_API void embedFont (DWFEmbeddedFont *pFont) throw ( DWFException )
_DWFTK_API void addResource (DWFPublishableResource *pResource) throw ( DWFException )
_DWFTK_API DWFIterator< DWFPublishableResource * > * getResources () throw ( DWFException )

Static Public Attributes

static char const keNormal_FullResolution = -1
 Do not quantize vertex normals.
static char const keNormal_DefaultResolution = 24
 Quantize vertex normals to 24 bits.
static char const keNormal_MaximumResolution = 72
 Quantize vertex normals to 72 bits.
static char const keVertex_FullResolution = -1
 Do not quantize vertex coordinates.
static char const keVertex_DefaultResolution = 54
 Quantize vertex coordinates to 54 bits.
static char const keVertex_MaximumResolution = 72
 Quantize vertex coordinates to 72 bits.
static char const keTextureParameter_FullResolution = -1
 Do not quantize texture parameter coordinates.
static char const keTextureParameter_DefaultResolution = 54
 Quantize texture parameter coordinates to 54 bits.
static char const keTextureParameter_MaximumResolution = 72
 Quantize texture parameter coordinates to 72 bits.

Classes

class  ResourceIterator
 An iterator for retrieving resources in the model.
Since:
7.0.1.
More...


Constructor & Destructor Documentation

_DWFTK_API DWFToolkit::DWFModel::DWFModel DWFOutputStream rModelStream,
const DWFString zModelTitle = "",
const DWFString zModelSource = "",
const DWFString zModelSourceID = ""
throw ()
 

Constructor

Use this constructor to manage the graphics stream manually.

Parameters:
rModelStream The output stream into which the w3d graphics be be written.
zModelTitle Corresponds to the EModel section title.
zModelSource Describes the source (application, component, etc.) of the model data.
zModelSourceID Uniquely identifies the source (document, file, database, etc.) of the model data.
Exceptions:
None 

_DWFTK_API DWFToolkit::DWFModel::DWFModel const DWFString zModelTitle = "",
const DWFString zModelSource = "",
const DWFString zModelSourceID = ""
throw ()
 

Constructor

Use this constructor to allow the model to manange it's own graphics stream.

Parameters:
zModelTitle Corresponds to the EModel section title.
zModelSource Describes the source (application, component, etc.) of the model data.
zModelSourceID Uniquely identifies the source (document, file, database, etc.) of the model data.
Exceptions:
None 

_DWFTK_API DWFToolkit::DWFModel::~DWFModel  )  throw ()
 

Destructor

Exceptions:
None 


Member Function Documentation

_DWFTK_API void DWFToolkit::DWFModel::addResource DWFPublishableResource pResource  )  throw ( DWFException ) [virtual]
 

Request that the resource be added to the section.

Use this method for adding thumbnails, previews, etc.

Parameters:
pResource The resource to add. This object will assume ownership of pResource and will delete it with DWFCORE_FREE_OBJECT.
Exceptions:
DWFException 

Reimplemented from DWFToolkit::DWFPublishableSection.

_DWFTK_API void DWFToolkit::DWFModel::close  )  throw ( DWFException )
 

Completes the model.

This method should be paired with open() to scope the model's usage.

Exceptions:
DWFException 

_DWFTK_API void DWFToolkit::DWFModel::createView const char *  zName,
W3DCamera rViewCamera
throw ( DWFException )
 

Create a named view.

For best streaming view performance always specify a default view - that is, one named "default". This should be done before any scene graphics are added.

Parameters:
zName A unique name for the view in the scene.
rViewCamera Defines the view.
Exceptions:
DWFException 

_DWFTK_API void DWFToolkit::DWFModel::disableAllCompression  )  throw ( DWFException )
 

Turns off every form of compression in the stream.

  • Turns off on-the-fly LZ compression.
  • Turns off connectivity compression.
  • Turns off global quantization compression.
  • Turns on full-resolution vertex coordinates.
  • Turns on full-resolution vertex normals.

Exceptions:
DWFException 

_DWFTK_API void DWFToolkit::DWFModel::embedFont DWFEmbeddedFont pFont  )  throw ( DWFException ) [virtual]
 

Request the provided font be embedded in the section.

Parameters:
pFont The font data object to embed. This object will assume ownership of pFont and will delete it with DWFCORE_FREE_OBJECT.
Exceptions:
DWFException 

Reimplemented from DWFToolkit::DWFPublishableSection.

_DWFTK_API void DWFToolkit::DWFModel::enableNormalsCompression char  nTotalNormalBits = keNormal_DefaultResolution  )  throw ()
 

Toggles the vertex normals quantization compression.

The default is 24 bits (8-bits each for i,j,k); use keNormal_FullResolution to disable normals compression

By default, VERTEX NORMALS COMPRESSION IS ENABLED. It is suggested that publishers enable this compression technique and adjust the bit resolution as small as possible without losing visual fidelity.

Parameters:
nTotalNormalBits The number of bits to use for all three dimensions for the quantization compression.
Exceptions:
None 

_DWFTK_API void DWFToolkit::DWFModel::enableVertexCompression char  nTotalVertexBits = keVertex_DefaultResolution,
char  nTotalParameterBits = keTextureParameter_FullResolution
throw ()
 

Toggles the vertex coordinate quantization compression.

The default is 54 bits (18-bits each for x,y,z).

Use keVertex_FullResolution to disable vertex compression. Use keTextureParameter_FullResolution to disable texture parameter compression.

By default, vertex coordinate compression is disabled. However, if publishers enable this compression technique, it is recommended to adjust the bit resolution as small as possible without losing visual fidelity. The following equation is recommended for determining this value:

                    nTotalVertexBits = 3 * ((unsigned int)(Log2(\e max_bounds/(\e epsilon/4.0))) + 1)
       
                    where:
       
                    \e epsilon is the maximum allowable error tolerable by the publishing application
                    (4.0 is a DWF-specific quality threshhold indicating that the quantization calculation
                    would introduce an additional 1/4 epsilon error at each vertex, at the most)
       
                    \e max_bounds is the absolute value of the largest bounding dimension: max(|x|,|y|,|z|)

Parameters:
nTotalVertexBits The number of bits to use for all three dimensions for the quantization compression.
nTotalParameterBits The number of bits to use for all three dimensions for the quantization compression.
Exceptions:
None 

_DWFTK_API void DWFToolkit::DWFModel::enableW3DCompression bool  bEnableStreamCompression = true,
bool  bEnableConnectivityCompression = true,
bool  bEnableGlobalQuantizationCompression = false
throw ( DWFException )
 

Toggles the various compression techniques.

Parameters:
bEnableStreamCompression Stream compression is enabled by default; this controls the inline LZ algorithm.
bEnableConnectivityCompression Connectivity compression is enabled by default; this controls the loseless edge breaker algorithm.
bEnableGlobalQuantizationCompression Global quantization compression is disabled by default; use this algorithm with caution as the underlying mechanism cannot account for object transformations and will not automatically calculate the world coordinates of each shell. This can lead to coordinates being wrapped around the quantization boundary which visually manifests itself as a "stretching" effect.
Exceptions:
DWFException 

_DWFTK_API void DWFToolkit::DWFModel::getBoundingVolume vector< double > &  rBounds  )  const throw ()
 

Returns the bounding volume for the entire scene.

For Bounding Cuboid, the vector rBounds is arranged as follows: Xmin, Ymin, Zmin, Xmax, Ymax, Zmax,

For Bounding Spheroid, the vector rBounds is arranged as follows: Xcenter, Ycenter, Zcenter, radius

Parameters:
rBounds The bounds of the scene.
Exceptions:
None 

_DWFTK_API const W3DCamera* DWFToolkit::DWFModel::getDefaultView  )  const throw ()
 

Returns the default view camera.

Returns:
The default view (may be NULL). The caller must not delete this pointer.
Exceptions:
None 

_DWFTK_API const float* const DWFToolkit::DWFModel::getEdgeColor  )  const throw ()
 

Returns the published edge color.

Returns:
A floating point RGB triplet (may be NULL). The caller must not delete this pointer.
Exceptions:
None 

_DWFTK_API DWFInputStream* DWFToolkit::DWFModel::getInputStream  )  throw ( DWFException ) [virtual]
 

Returns a stream from which the publishable data can be read.

Returns:
The data stream. The caller must release the stream with DWFCORE_FREE_OBJECT.
Exceptions:
DWFException 

Implements DWFToolkit::DWFPublishable.

_DWFTK_API const DWFString& DWFToolkit::DWFModel::getMIMEType  )  throw ( DWFException ) [virtual]
 

Returns the MIME type of the publishable data.

Returns:
The MIME type.
Exceptions:
DWFException 

Implements DWFToolkit::DWFPublishable.

_DWFTK_API const DWFString& DWFToolkit::DWFModel::getModelSource  )  const throw ()
 

Returns the name of the source of the model.

Returns:
Describes the source (application, component, etc.) of the model data.
Exceptions:
None 

_DWFTK_API const DWFString& DWFToolkit::DWFModel::getModelSourceID  )  const throw ()
 

Returns an identifier of the source of the model.

Returns:
Uniquely identifies the source (document, file, database, etc.) of the model data.
Exceptions:
None 

_DWFTK_API const DWFString& DWFToolkit::DWFModel::getModelTitle  )  const throw ()
 

Returns the title of the model.

Returns:
Corresponds to the EModel section title.
Exceptions:
None 

_DWFTK_API tePolygonHandedness DWFToolkit::DWFModel::getPolygonHandedness  )  const throw ()
 

Returns the polygon handedness setting.

Returns:
An enumeration indicating the vertex winding order for all faces and polygons in the model.
Exceptions:
None 

_DWFTK_API DWFIterator<DWFPublishableResource*>* DWFToolkit::DWFModel::getResources  )  throw ( DWFException ) [virtual]
 

Returns the list of resources added to this section.

Returns:
A pointer to an iterator than will provide the resources. This pointer must be deleted by the caller with DWFCORE_FREE_OBJECT but the resource pointers themselves should not be.
Exceptions:
DWFException 

Reimplemented from DWFToolkit::DWFPublishableSection.

_DWFTK_API void DWFToolkit::DWFModel::getTransform double *  pTransform  )  const throw ()
 

Returns the model unit transform.

Returns:
Used to transform model space into the eModelUnits unit space. If this parameter is not specified, identity will be assumed. If this parameter is specified, it must be defined in order (left -> right) as follows:
 using I as an example:
                    ( (1, 0, 0, 0) (0, 1, 0, 0) (0, 0, 1, 0) (0, 0, 0, 1) )
       
                    0  1  2  3   4  5  6  7   8  9  10 11  12 13 14 15
Exceptions:
None 

_DWFTK_API DWFUnits::teType DWFToolkit::DWFModel::getUnits  )  const throw ()
 

Returns the model units.

Returns:
A enumeration indicating into which unit space the model should be transformed by the matrix returned from getTransform().
Exceptions:
None 

_DWFTK_API void DWFToolkit::DWFModel::open tePolygonHandedness  ePolygonHandedness,
DWFUnits::teType  eModelUnits,
double *  pTransform = NULL,
bool  bUseDefaultLighting = true,
bool  bUsePublishedEdges = false,
bool  bUseSilhouetteEdges = false
throw ( DWFException )
 

Prepares the model for first use.

Parameters:
ePolygonHandedness Indicates the vertex winding order for all faces and polygons in the model. To use a different handedness, use the TK_Heuristic op-code to manually override the setting where appropriate.
eModelUnits Indicates into which unit space the pTransform matrix will transform the model space.
pTransform Used to transform model space into the eModelUnits unit space. If this parameter is not specified, identity will be assumed. If this parameter is specified, it must be defined in order (left -> right) as follows:
 using I as an example:
                                            ( (1, 0, 0, 0) (0, 1, 0, 0) (0, 0, 1, 0) (0, 0, 0, 1) )
       
                                               0  1  2  3   4  5  6  7   8  9  10 11  12 13 14 15
bUseDefaultLighting If true, a flag will be set to recommend any viewer to use it's own default lighting. If false and there are lights in the scene, viewers should honor them, otherwise the it is recommended that the viewer use defaults.
bUsePublishedEdges Must be set to true if any segment in the model contains interior edge geometry that is preferred to be used by the viewer as wireframe display. If true, only those segments opened with published edges on will be shown in wireframe; all other lines will be invisible. If false, the viewer may choose to use its default algorithm.
bUseSilhouetteEdges If true, the viewer should calculate and display silhouette edges in wireframe mode, regardless of the published interior edge conditions. If false, the viewer should not calculate nor display silhouette edges in wireframe mode, regardless of the published interior edge conditions.
Exceptions:
DWFException 

_DWFTK_API DWFIncludeSegment DWFToolkit::DWFModel::openIncludeSegment  )  throw ( DWFException )
 

Opens a new segment for this model's include library.

Returns:
An include library segment.
Exceptions:
DWFException 

_DWFTK_API DWFSegment DWFToolkit::DWFModel::openSegment  )  throw ( DWFException )
 

Opens a new segment.

Returns:
A scene segment.
Exceptions:
DWFException 

_DWFTK_API DWFStyleSegment DWFToolkit::DWFModel::openStyleSegment  )  throw ( DWFException )
 

Opens a new segment for this model's style library.

Returns:
A style library segment.
Exceptions:
DWFException 

_DWFTK_API void DWFToolkit::DWFModel::publish DWFPublisher rPublisher  )  throw ( DWFException ) [virtual]
 

Use the publisher to extract the model structure.

Parameters:
rPublisher The publisher.
Exceptions:
DWFException 

Implements DWFToolkit::DWFPublishableSection.

_DWFTK_API void DWFToolkit::DWFModel::setBoundingCube float  nMinX,
float  nMinY,
float  nMinZ,
float  nMaxX,
float  nMaxY,
float  nMaxZ
throw ( DWFException )
 

Establish the bounding cuboid for the entire scene.

Important: Setting the bounding volume before writing any graphics data will faciliate global quantization; and the opposite is also true: not establishing this data will prevent globalization quantization calculations.

Parameters:
nMinX 
nMinY 
nMinZ 
nMaxX 
nMaxY 
nMaxZ 
Exceptions:
DWFException 

_DWFTK_API void DWFToolkit::DWFModel::setBoundingSphere float  nCenterX,
float  nCenterY,
float  nCenterZ,
float  nRadius
throw ( DWFException )
 

Establish the bounding spheroid for the entire scene

Important: Setting the bounding volume before writing any graphics data will faciliate global quantization; and the opposite is also true: not establishing this data will prevent globalization quantization calculations.

Parameters:
nCenterX 
nCenterY 
nCenterZ 
nRadius 
Exceptions:
DWFException 

_DWFTK_API void DWFToolkit::DWFModel::setEdgeColor float  anRGB[3]  )  throw ()
 

Changes the preferred color for wireframe mode edges regardless of how they are defined (published or inferred.)

Parameters:
anRGB RGB floating point color triplet.
Exceptions:
None 

_DWFTK_API bool DWFToolkit::DWFModel::useModelLighting  )  const throw ()
 

Returns a model lighting flag.

Returns:
If true, a flag will be set to recommend any viewer to use it's own default lighting. If false and there are lights in the scene, viewers should honor them, otherwise the it is recommended that the viewer use defaults.
Exceptions:
None 

_DWFTK_API bool DWFToolkit::DWFModel::useSilhouetteEdges  )  const throw ()
 

Returns the silhouette edge preferrence.

Returns:
If true, the viewer should calculate and display silhouette edges in wireframe mode, regardless of the published interior edge conditions. If false, the viewer should not calculate nor display silhouette edges in wireframe mode, regardless of the published interior edge conditions.
Exceptions:
None 


The documentation for this class was generated from the following file:
Generated on Tue May 17 12:39:14 2005 for Autodesk DWF Toolkit by  doxygen 1.4.1