I3DExGeometricPrimitive Struct Reference
[External Interfaces]

Inheritance diagram for I3DExGeometricPrimitive:

List of all members.

Public Member Functions
virtual void MCCOMAPI	GetBoundingBox (TBBox3D &bbox)=0
virtual MCCOMErr MCCOMAPI	EnumPatches (EnumPatchesCallback callback, void *privData, boolean &closed)=0
virtual MCCOMErr MCCOMAPI	GetNbrLOD (int16 &nbrLod)=0
virtual MCCOMErr MCCOMAPI	GetLOD (int16 lodIndex, real &lod)=0
virtual MCCOMErr MCCOMAPI	GetFacetMesh (uint32 lodIndex, FacetMesh **outMesh)=0
virtual MCCOMErr MCCOMAPI	GetFacetMesh (real lod, FacetMesh **outMesh)=0
virtual boolean MCCOMAPI	CanBeSplit ()=0
virtual MCCOMErr MCCOMAPI	SplitPrimitive (TMCCountedPtrArray< I3DExGeometricPrimitive > &subParts, TMCArray< TTransform3D > &subPartPositions)=0
virtual uint32 MCCOMAPI	GetUVSpaceCount ()=0
virtual MCCOMErr MCCOMAPI	GetUVSpace (uint32 uvSpaceID, UVSpaceInfo *uvSpaceInfo)=0
virtual MCCOMErr MCCOMAPI	UV2XYZ (TVector2 *uv, uint32 uvSpaceID, TVector3 *resultPosition, boolean *inUVSpace)=0
virtual MCCOMErr MCCOMAPI	GetUVSpaceRDS5 (uint32 uvSpaceID, UVSpaceInfoRDS5 *uvSpaceInfoRDS5)=0
virtual MCCOMErr MCCOMAPI	AppendToRenderables (const TTransform3D &worldFromModelTfm, TRenderableAndTfmArray &renderableAndTfm)=0
virtual boolean MCCOMAPI	AutoSwitchToModeler () const =0
virtual boolean MCCOMAPI	IsBBoxPickable () const =0
virtual boolean MCCOMAPI	IsExcludedFromTripleBuffer ()=0
virtual void MCCOMAPI	GetDefaultShader (I3DShShader **shader)=0
virtual void MCCOMAPI	ChangedData ()=0

---

Detailed Description

Geometric primitives define a geometric object. They return a list of facets or bicubic patches and can give information on an object’s UV Space. The shell will check for patches first by calling EnumPatches() and then call GetFacetMesh() if EnumPatches() fails. At least one or both of these two methods must be implemented.

In addition to describing geometry, a geometric primitive can define a custom ray-tracing routine rather than relying only on facets or patches. This is done by inheriting from the IRaytracablePrimitive Interface in addition to I3DExGeometricPrimitive (or TBasicPrimitive).

A primitive can also support skinning (skinning is the deformation of the primitive geometry using a skeleton composed of bones). This is done by inheriting from the I3dExSkinable Interface in addition to I3DExGeometricPrimitive (or TBasicPrimitive).

Rather than defining geometry, a primitive can also describe a volume. This is achieved by inheriting from the IVolumePrimitive Interface as well as I3DExGeometricPrimitive (or TBasicPrimitive).

The structure of a primitive is a bit more complex than the average component:

There are 2 COM objects to consider:

• The Primitive that supports I3DShExternalPrimitive, I3DShPrimitive and I3DShObject.
• The Primitive Component that supports IShComponent, I3DShPrimitiveComponent and I3DExGeometricPrimitive

For advanced users: You should note that there are actually 3 C++ object (The primitive, the primitive component and the primitive light). However the primitive component and the external primitive are aggregated by COM which means that you can be considered as one single COM object).

To get a pointer to a I3DShExternalPrimitive from a I3DExGeometricPrimitive, you can use the following code:

    TMCCountedPtr<I3DShPrimitiveComponent> primitiveComponent;
    exPrimitive->QueryInterface(IID_I3DShPrimitiveComponent,(void**)&primitiveComponent);
    ThrowIfNil(primitiveComponent);
   
    TMCCountedPtr<I3DShPrimitive> primitive;
    primitiveComponent->GetPrimitive(&primitive);
    ThrowIfNil(primitive);
   
    TMCCountedPtr<I3DShExternalPrimitive> externalPrimitive;
    primitive->QueryInterface(IID_I3DShExternalPrimitive.(void**)&externalPrimitive);

To access I3DExGeometricPrimitive from I3DShPrimitive, you can use the following code:

    TMCCountedPtr<I3DShExternalPrimitive> externalPrimitive;
    shPrimitive->QueryInterface(IID_I3DShExternalPrimitive.(void**)&externalPrimitive);
    ThrowIfNil(externalPrimitive);
    
    TMCCountedPtr<IShComponent> primitiveComponent;
    externalPrimitive->GetPrimitiveComponent(&primitiveComponent);
    ThrowIfNil(primitiveComponent);
   
    TMCCountedPtr<I3DExGeometricPrimitive> externalPrimitive;
    primitiveComponent->QueryInterface(IID_I3DExGeometricPrimitive,(void**)&externalPrimitive);

This code might seem a bit complicated at first but it is actually simple. You have two COM objects that point on each other. I3DShExternalPrimitive::GetPrimitiveComponent() and I3DShPrimitiveComponent::GetPrimitive() allow you to get a pointer from one object to the other. The rest is only calling QueryInterface to get the right interface on each object.

See also:

I3DShPrimitiveComponent

I3DShExternalPrimitive

I3DShPrimitive

---

Member Function Documentation

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::AppendToRenderables (  const TTransform3D &  worldFromModelTfm, TRenderableAndTfmArray &  renderableAndTfm )  [pure virtual]

Appends the renderable to the renderable array. This is used to append extra renderables on top of the geometry itself. Parameters: worldFromModelTfm  The global transform of the primitive. renderableAndTfm  The array of renderable and transforms. Implemented in TBasicPrimitive.

virtual boolean MCCOMAPI I3DExGeometricPrimitive::AutoSwitchToModeler (   )  const [pure virtual]

Returns true if the primitive should be open in its modeler immediately after its insertion Implemented in TBasicPrimitive.

virtual boolean MCCOMAPI I3DExGeometricPrimitive::CanBeSplit (   )  [pure virtual]

Returns true if the primitive can split itself into sub parts of the same type. Implemented in TBasicPrimitive.

virtual void MCCOMAPI I3DExGeometricPrimitive::ChangedData (   )  [pure virtual]

Do not use. Temporary call. Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::EnumPatches (  EnumPatchesCallback  callback, void *  privData, boolean &  closed )  [pure virtual]

Returns the primitive as a list of bicubic patches. It is recommended to use GetFacetMesh() instead. Parameters: callback  Callback procedure that should be called for each Patch generated by the Primitive. privData  Points to private data from the Shell. Pass this pointer to callback. closed  Returns True when the surface is closed. This helps set the backface mask correctly. Implemented in TBasicPrimitive.

virtual void MCCOMAPI I3DExGeometricPrimitive::GetBoundingBox (  TBBox3D &  bbox  )  [pure virtual]

Computes the bounding box of the primitive to the 3D Shell. If this call is not implemented the bounding box will be calculated automatically from the patches or facets list. However it is recommended to implement it to speed up the bounding box calculation. Parameters: bbox  A reference to a structure where the bounding box should be stored.

virtual void MCCOMAPI I3DExGeometricPrimitive::GetDefaultShader (  I3DShShader **  shader  )  [pure virtual]

Returns the default shader for this primitive. This is called each time a primitive is inserted in a scene without a shader Returns: A pointer to the shader that should be used for this primitive (NULL to use the default master shader) Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::GetFacetMesh (  real  lod, FacetMesh **  outMesh )  [pure virtual]

Never implement that one, reserved for future use (primitives with an infinite number of resolutions) Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::GetFacetMesh (  uint32  lodIndex, FacetMesh **  outMesh )  [pure virtual]

Returns the Facet Mesh for this lod index. Parameters: lodIndex  The index of the level of detail that is asked (see GetNbrLOD()) outMesh  A pointer to a pointer that should be set to point on the FacetMesh. Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::GetLOD (  int16  lodIndex, real &  lod )  [pure virtual]

Return the floating point value of the level of detail that corresponds to the 0-based 'lodIndex'. (lodIndex=0 means highest resolution) Parameters: lodIndex  The index of the level of detail lod  The returned lod precision. Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::GetNbrLOD (  int16 &  nbrLod  )  [pure virtual]

Returns the number of levels of detail (lod) of the primitive. This value is used to determine the lodIndex in GetLOD(). Parameters: nbrLod  The number returned for the levels of detail for the primitive. Note: : Read the technical explanations in BasicPrimitive.cpp to learn everything about LOD (Level Of Details) management, and multi-resolution support. Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::GetUVSpace (  uint32  uvSpaceID, UVSpaceInfo *  uvSpaceInfo )  [pure virtual]

Returns the information regarding a particular uvSpace (= shading domain). Parameters: uvSpaceID  The ID of the uvspace (0 based index) uvSpaceInfo  A pointer to a structure where the information will be stored. Implemented in TBasicPrimitive.

virtual uint32 MCCOMAPI I3DExGeometricPrimitive::GetUVSpaceCount (   )  [pure virtual]

Returns the number of UV space on the primitives. Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::GetUVSpaceRDS5 (  uint32  uvSpaceID, UVSpaceInfoRDS5 *  uvSpaceInfoRDS5 )  [pure virtual]

Returns the information regarding a particular uvSpace (= shading domain). To be implemented only if your primitive existed in RDS 5 or earlier, so that UV spaces can be mapped properly to the new 0..1 boundaries Parameters: uvSpaceID  The ID of the uvspace (0 based index) uvSpaceInfo  A pointer to a structure where the information will be stored. Implemented in TBasicPrimitive.

virtual boolean MCCOMAPI I3DExGeometricPrimitive::IsBBoxPickable (   )  const [pure virtual]

Returns true if the primitive can be picked in the 3D View when clicking on its bounding box. Usually, you want to reply no, since the picking is done thru a ray-tracing hit test. However, some primitives such as volumic primitives or particles systems may want to answer yes. Default implementation in TBasicPrimitive returns false. Implemented in TBasicPrimitive.

virtual boolean MCCOMAPI I3DExGeometricPrimitive::IsExcludedFromTripleBuffer (   )  [pure virtual]

Return true if its instances should be excluded from the triple buffer (eg used for skinning) Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::SplitPrimitive (  TMCCountedPtrArray< I3DExGeometricPrimitive > &  subParts, TMCArray< TTransform3D > &  subPartPositions )  [pure virtual]

Builds a list of sub-parts of itself. 'subPartPositions' gives the relative position of each sub part in the object local coordinates. Both arrays need to be of same size. Note: the original primitive needs to remain intact. Parameters: subParts  An array of sub primitives. subPartPositions  For each sub primitives, its transform. Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::UV2XYZ (  TVector2 *  uv, uint32  uvSpaceID, TVector3 *  resultPosition, boolean *  inUVSpace )  [pure virtual]

Returns the position in 3D of a point given a set of UV coordinates. This is useful if you want to calculate a UV texture from a 3D shaders for instance. Returns: MC_S_OK if it is implemented, E_NOTIMPL if it isn't (in which case a default implementation will be used by the shell). Parameters: uv  The uv coordinates used as input uvSpaceID  The uv space ID to which this uv coordinates corresponds resultPosition  The 3D Position that is returned. inUVSpace  Returns true if the point was found in the upSpaceID specified. Implemented in TBasicPrimitive.

---

The documentation for this struct was generated from the following file:

• I3dExPrimitive.h

---