I3DExGeometricPrimitive Struct Reference
[External Interfaces]

Inheritance diagram for I3DExGeometricPrimitive:
IMCUnknown TBasicPrimitive

List of all members.

Public Member Functions

virtual void MCCOMAPI GetBoundingBox (TBBox3D &bbox)=0
virtual void MCCOMAPI GetRenderingBoundingBox (TBBox3D &bbox)=0
virtual MCCOMErr MCCOMAPI GetApproximateBoundingBox (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 boolean MCCOMAPI HasRenderingFacetMesh ()=0
virtual MCCOMErr MCCOMAPI GetRenderingFacetMesh (FacetMesh **outMesh)=0
virtual void MCCOMAPI GetRenderingMesh (MeshDataStructure::TMeshList **meshList)=0
virtual void MCCOMAPI GetFaceSetList (TMCCountedPtrArray< TFaceSet > &faceSetList)=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 boolean MCCOMAPI CanRenameUVSpace ()=0
virtual MCCOMErr MCCOMAPI RenameUVSpace (uint32 uvSpaceID, const TMCString &name)=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, TMCString *name=nil)=0
virtual void MCCOMAPI GetDefaultShaderInfo (int32 &outShaderResID, int32 &outNameStringResID, int32 &outNameStringIndex)=0
virtual void MCCOMAPI ChangedData ()=0
virtual MCCOMErr MCCOMAPI GetWizardPath (TMCString &path)=0
virtual boolean MCCOMAPI CanConvertToOtherModeler ()=0
virtual void MCCOMAPI ChangeLocalTimeInHit (RayHitParameters &params)=0
virtual boolean MCCOMAPI NeedAnimatedShader ()=0
virtual boolean MCCOMAPI IsGenerator () const =0
virtual void MCCOMAPI GetPreviewObject (I3DShMasterShader *masterShader, I3DShObject **object, I3DShTreeElement **previewTree, I3DShTreeElement **additionnalChildInstance)=0
virtual int32 MCCOMAPI GetPrimitiveInstanceType () const =0
virtual boolean MCCOMAPI IsScalable () const =0
virtual real32 MCCOMAPI GetScalingFactor () const =0
virtual void MCCOMAPI SetScalingFactor (real32 inValue)=0
virtual boolean MCCOMAPI CanImportData (I3DImportData *inImportData, I3DShInstance *inInstance)=0
 Returns true if the Primitive can import the given data on the given instance.
virtual boolean MCCOMAPI ImportData (I3DImportData *inImportData, I3DShInstance *inInstance)=0
 Imports the given data on the given instance, returns false if the import was aborted.
virtual boolean MCCOMAPI ImplementDisplacementMapping ()=0
virtual void MCCOMAPI DisplacementShaderChanged ()=0
virtual ELODParamType MCCOMAPI GetLODParamType () const =0
virtual int16 MCCOMAPI GetLODIndex (real32 distance) const =0
virtual void GetAdditionalBoundingBoxVertices (TMCArray< TVector3 > &additionalVertices) const =0
virtual void MCCOMAPI AboutToRemoveInstance (I3DShInstance *instance)=0
virtual boolean MCCOMAPI ShouldDeleteWithInstance (I3DShInstance *inInstance)=0
 return true if the master should be deleted with the instance (used for figures)

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:

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 void MCCOMAPI I3DExGeometricPrimitive::AboutToRemoveInstance ( I3DShInstance instance  )  [pure virtual]

Implemented in TBasicPrimitive.

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. If the function returns MC_S_FALSE instead of MC_S_OK, the default renderable will not be visible.

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]

Never implement that one, reserved for future use (primitives with an infinite number of resolutions) Returns true if the primitive can split itself into sub parts of the same type.

Implemented in TBasicPrimitive.

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

Returns true if need an apparent button to convert to other modeler.

Implemented in TBasicPrimitive.

virtual boolean MCCOMAPI I3DExGeometricPrimitive::CanImportData ( I3DImportData inImportData,
I3DShInstance inInstance 
) [pure virtual]

Returns true if the Primitive can import the given data on the given instance.

Implemented in TBasicPrimitive.

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

Returns true if the primitive can rename uv spaces (ie. implements RenameUVSpace()).

Implemented in TBasicPrimitive.

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

Do not use. Temporary call.

Implemented in TBasicPrimitive.

virtual void MCCOMAPI I3DExGeometricPrimitive::ChangeLocalTimeInHit ( RayHitParameters params  )  [pure virtual]

Let the object change the local time after a hit

Parameters:
params the parameters of the hit, only params.fHit->fTime should be changed

Implemented in TBasicPrimitive.

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

Called to invalidate the primitive when the displacement shader has changed

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 I3DExGeometricPrimitive::GetAdditionalBoundingBoxVertices ( TMCArray< TVector3 > &  additionalVertices  )  const [pure virtual]

Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::GetApproximateBoundingBox ( TBBox3D bbox  )  [pure virtual]

Computes the approximate bounding box (should not used any other object geometry).

Parameters:
bbox A reference to a structure where the bounding box should be stored.

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,
TMCString name = nil 
) [pure virtual]

Returns the default shader for this primitive. This is called each time a primitive is inserted in a scene without a shader

Parameters:
shader should return a pointer to the shader that should be used for this primitive (NULL to use the default master shader)
name if not nil can fill with the name of the default shader

Implemented in TBasicPrimitive.

virtual void MCCOMAPI I3DExGeometricPrimitive::GetDefaultShaderInfo ( int32 &  outShaderResID,
int32 &  outNameStringResID,
int32 &  outNameStringIndex 
) [pure virtual]

Returns the info necessary to load the default shader for this primitive. This is called each time a primitive is inserted in a scene without a shader.

Parameters:
outShaderResID Resource ID of the SHAD resource storing the shader
outNameStringResID Resource ID of the STR# resource to use for the shader's name
outNameStringIndex Index of the string for the shader name

Implemented in TBasicPrimitive.

virtual void MCCOMAPI I3DExGeometricPrimitive::GetFaceSetList ( TMCCountedPtrArray< TFaceSet > &  faceSetList  )  [pure virtual]

Gets the list of face sets associated with the primitive.

Parameters:
faceSetList The face set list that is returned.

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 int16 MCCOMAPI I3DExGeometricPrimitive::GetLODIndex ( real32  distance  )  const [pure virtual]

Implemented in TBasicPrimitive.

virtual ELODParamType MCCOMAPI I3DExGeometricPrimitive::GetLODParamType (  )  const [pure virtual]
Returns:
The type of information used to calculate the appropriate LOD

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 void MCCOMAPI I3DExGeometricPrimitive::GetPreviewObject ( I3DShMasterShader masterShader,
I3DShObject **  object,
I3DShTreeElement **  previewTree,
I3DShTreeElement **  additionnalChildInstance 
) [pure virtual]

Return the Master object to preview if different from main one. Return NULL if it is the same,

Parameters:
masterShader the master shader being previewed
object the object to use to preview the shader
previewTree a tree to set the transform of the preview object (only the transform will be used)
additionnalChild the master object can also add an instance that will be used for the preview as well, puting it as child of the previewed object

Implemented in TBasicPrimitive.

virtual int32 MCCOMAPI I3DExGeometricPrimitive::GetPrimitiveInstanceType (  )  const [pure virtual]

Return the instance type for this primitive.

See also:
I3DShInstance::EInstanceType

Implemented in TBasicPrimitive.

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

Computes the bounding box for rendering.

Parameters:
bbox A reference to a structure where the bounding box should be stored.

Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::GetRenderingFacetMesh ( FacetMesh **  outMesh  )  [pure virtual]

Returns the mesh that should be used for final rendering.

You should only implement this method if you use a mesh for previewing that is different from the the mesh for final rendering.

Parameters:
outMesh A pointer to a pointer to the FacetMesh that is returned.
Returns:
MC_S_OK if implemented, MC_E_NOTIMPL otherwise

Implemented in TBasicPrimitive.

virtual void MCCOMAPI I3DExGeometricPrimitive::GetRenderingMesh ( MeshDataStructure::TMeshList **  meshList  )  [pure virtual]

Returns a pointer to the rendering mesh associated with the primitive. Note that the mesh should not be cached by the primitive so it can be modified by the caller.

The mesh can be composed either of triangles or quads. More complexe polygons should be triangulated before the mesh is returned.

It is the caller responsability to call release on the mesh once it is not used anymore.

Parameters:
meshList The mesh list that is returned. NULL if this call is not supported (in which case the caller can use the facet mesh)

Implemented in TBasicPrimitive.

virtual real32 MCCOMAPI I3DExGeometricPrimitive::GetScalingFactor (  )  const [pure virtual]

Returns the scaling that should be applied to the primitive, i.e. the number of inches in the primitive's unit.

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)
uvSpaceInfoRDS5 A pointer to a structure where the information will be stored.

Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::GetWizardPath ( TMCString path  )  [pure virtual]

Returns the path to the primitive wizard file (wizard.txt) from the application folder.

Parameters:
path path to the primitive wizard file from the application folder

Implemented in TBasicPrimitive.

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

Returns true if this primitive has a mesh used only for final rendering. If it returns false, you can assume that the mesh for lod 0 and the rendering mesh are the same.

Implemented in TBasicPrimitive.

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

Returns true if the primite can apply the displacement mapping by itself

Implemented in TBasicPrimitive.

virtual boolean MCCOMAPI I3DExGeometricPrimitive::ImportData ( I3DImportData inImportData,
I3DShInstance inInstance 
) [pure virtual]

Imports the given data on the given instance, returns false if the import was aborted.

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 boolean MCCOMAPI I3DExGeometricPrimitive::IsGenerator (  )  const [pure virtual]

Return true if the object can generate sub instances if true the component should also implements I3DExInstancePrimitive

Implemented in TBasicPrimitive.

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

If true, the primitive is scaled at insertion in a scene, so that one unit for the primitive corresponds to one unit in the scene.

Implemented in TBasicPrimitive.

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

Return true if the object uses local time and therefore will need animated shader

Implemented in TBasicPrimitive.

virtual MCCOMErr MCCOMAPI I3DExGeometricPrimitive::RenameUVSpace ( uint32  uvSpaceID,
const TMCString name 
) [pure virtual]

Rename a particular uvSpace (= shading domain).

Parameters:
uvSpaceID The ID of the uvspace (0 based index)
name The new name of the uvspace.

Implemented in TBasicPrimitive.

virtual void MCCOMAPI I3DExGeometricPrimitive::SetScalingFactor ( real32  inValue  )  [pure virtual]

Sets the scaling factor of the primitive.

Parameters:
inValue the number of inches to which the primitive's unit is equivalent

Implemented in TBasicPrimitive.

virtual boolean MCCOMAPI I3DExGeometricPrimitive::ShouldDeleteWithInstance ( I3DShInstance inInstance  )  [pure virtual]

return true if the master should be deleted with the instance (used for figures)

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:
Generated on Mon Apr 26 22:47:37 2010 for Carrara SDK Doc by  doxygen 1.6.3