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 ¶ms)=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) |
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.
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.
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
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.
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).
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.
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
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.
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.
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.
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)
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] |
Implemented in TBasicPrimitive.
Returns the number of levels of detail (lod) of the primitive. This value is used to determine the lodIndex in GetLOD().
nbrLod | The number returned for the levels of detail for the primitive. |
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,
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.
Implemented in TBasicPrimitive.
virtual void MCCOMAPI I3DExGeometricPrimitive::GetRenderingBoundingBox | ( | TBBox3D & | bbox | ) | [pure virtual] |
Computes the bounding box for rendering.
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.
outMesh | A pointer to a pointer to the FacetMesh that is returned. |
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.
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).
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
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.
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).
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.
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.
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.
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.