I3DShCamera Struct Reference
[Shell Interfaces]

Inheritance diagram for I3DShCamera:
IMCUnknown

List of all members.

Public Member Functions

virtual MCCOMErr MCCOMAPI GetGlobalToCameraTransform (TTransform3D *transform) const =0
virtual MCCOMErr MCCOMAPI Preset (uint32 preset, const TVector3 &aimedPoint, real distance)=0
virtual boolean MCCOMAPI IsProjectionAffine (void) const =0
virtual boolean MCCOMAPI PreProject3DTo2D (const TVector3 &cameraPosition, TVector4 &projectedPosition) const =0
virtual boolean MCCOMAPI Project3DTo2D (const TVector3 *position, TVector2 *resultScreenPosition, real *resultDistanceToScreen) const =0
virtual boolean MCCOMAPI CreateRay (const TVector2 *screenPosition, TVector3 *resultOrigin, TVector3 *resultDirection) const =0
virtual boolean MCCOMAPI CreateRay (const TVector2 &screenPosition, const TVector2 &screenDerivate, Ray3D &ray) const =0
virtual I3DExCamera *MCCOMAPI GetValidExCameraNoAddRef ()=0
virtual MCCOMErr MCCOMAPI GetRenderUVBox (TBBox2D *uvBox, uint32 width, uint32 height, real pixelAspectRatio) const =0
virtual MCCOMErr MCCOMAPI SetCameraComponent (int32 kindID)=0
virtual MCCOMErr MCCOMAPI SetCameraComponent (IShComponent *cameraComponent, ECloneMode cloneMode)=0
virtual MCCOMErr MCCOMAPI GetCameraComponent (IShComponent **cameraComponent)=0
virtual void MCCOMAPI GetStandardCameraInfo (TStandardCameraInfo &cameraInfo) const =0
virtual void MCCOMAPI SetCanonicalCameraType (ECanonicalCameraType canonicalCameraType, real *canonicalScale)=0
virtual ECanonicalCameraType
MCCOMAPI 
GetCanonicalCameraType ()=0
virtual void MCCOMAPI SetProductionOffset (const TVector2 &inOffset)=0
virtual TVector2 MCCOMAPI GetProductionOffset () const =0
virtual void MCCOMAPI SetProductionZoom (real zoom)=0
virtual real MCCOMAPI GetProductionZoom () const =0
virtual I3DShTreeElement *MCCOMAPI GetTreeElement ()=0
virtual void MCCOMAPI SetRenderingUVBox (const TBBox2D &inUVBox)=0

Detailed Description

Cameras define the projection from the 3D world to the 2D screen on which the image is rendered.

The structure of a camera is a little bit more complex that the typical component. It is similar to the structure of Lights and Primitives.

There are 2 COM objects to consider:

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

To get a pointer to a I3DShCamera from a I3DExCamera, you can use the following code:

 TMCCountedPtr<I3DShTreeElementMember> cameraComponent;
 exCamera->QueryInterface(IID_I3DShTreeElementMember,(void**)&cameraComponent);
 ThrowIfNil(cameraComponent);

 TMCCountedPtr<I3DShTreeElement> cameraTree;
 cameraComponent->GetTreeElement(&cameraTree);
 ThrowIfNil(cameraTree);

 TMCCountedPtr<I3DShCamera> shCamera;
 cameraTree->QueryInterface(IID_I3DShCamera.(void**)&shCamera);

To access I3DExCamera from I3DShCamera, you can use the following code:

 TMCCountedPtr<IShComponent> cameraComponent;
 shCamera->GetCameraComponent(&cameraComponent);
 ThrowIfNil(cameraComponent);

 TMCCountedPtr<I3DExCamera> exCamera;
 cameraComponent->QueryInterface(IID_I3DExCamera,(void**)&exCamera);

This code might seem a bit complicated at first but it is actually simple. You have two COM objects that point on each other. I3DShCamera::GetCameraComponent() and I3DShTreeElementMember::GetTreeElement() 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.

Whenever it is possible you should use the Shell interface (I3DShCamera) to access the camera because the Shell will make sure that the parameter map of the external component is valid. This is especially important if the component is animated. For more information on components see the Overview of the SDK.

See also:
I3DExCamera

Member Function Documentation

virtual boolean MCCOMAPI I3DShCamera::CreateRay ( const TVector2 screenPosition,
const TVector2 screenDerivate,
Ray3D ray 
) const [pure virtual]

Generates a ray through a given screen location with a given thickness (screenDerivate).

Parameters:
screenPosition The position in screen coordinates.
screenDerivate The delta of the position in screen coordinates (the derivate of the ray should be proportional to that).
ray The ray that is returned.
virtual boolean MCCOMAPI I3DShCamera::CreateRay ( const TVector2 screenPosition,
TVector3 resultOrigin,
TVector3 resultDirection 
) const [pure virtual]

Generates a ray through a given screen location. Note that in this case the ray has no width. To get a ray with a width you should use the next call.

Parameters:
screenPosition The position in screen coordinates.
resultOrigin The origin of the ray that is returned.
resultDirection The direction of the ray that is returned.
virtual MCCOMErr MCCOMAPI I3DShCamera::GetCameraComponent ( IShComponent **  cameraComponent  )  [pure virtual]

Returns a pointer to the camera component.

Parameters:
cameraComponent A pointer to the camera component.
virtual ECanonicalCameraType MCCOMAPI I3DShCamera::GetCanonicalCameraType (  )  [pure virtual]

Returns the type of camera (see I3DEditorHostPart for more info on canonical cameras).

virtual MCCOMErr MCCOMAPI I3DShCamera::GetGlobalToCameraTransform ( TTransform3D transform  )  const [pure virtual]

Returns the transform from Global coordinates to Camera Coordinates. Note that this not the same thing as asking the transform of the camera on the corresponding tree element because the scaling is taken out in this case.

Parameters:
transform A structure where the transform can be stored.
virtual TVector2 MCCOMAPI I3DShCamera::GetProductionOffset (  )  const [pure virtual]

Returns the product offset.

virtual real MCCOMAPI I3DShCamera::GetProductionZoom (  )  const [pure virtual]

Returns the size (zoom) of the production frame.

virtual MCCOMErr MCCOMAPI I3DShCamera::GetRenderUVBox ( TBBox2D uvBox,
uint32  width,
uint32  height,
real  pixelAspectRatio 
) const [pure virtual]

Returns the production frame in screen coordinates.

Parameters:
uvBox The production frame in screen coordinates that is returned.
width The width of the image to render
height The height of the image to render
pixelAspectRatio The pixel ratio that should be used.
virtual void MCCOMAPI I3DShCamera::GetStandardCameraInfo ( TStandardCameraInfo cameraInfo  )  const [pure virtual]

Returns the standard camera info used in the interactive renderers (in the 3D View). For perfomance reasons the interactive renderers use this function to get an approximation of the camera that is used to perform the rendering.

Parameters:
cameraInfo A reference to a structure where the definition of the camera is stored.
virtual I3DShTreeElement* MCCOMAPI I3DShCamera::GetTreeElement (  )  [pure virtual]

Returns the I3DShTreeElement interface. This call is faster than calling QueryInterface.

virtual I3DExCamera* MCCOMAPI I3DShCamera::GetValidExCameraNoAddRef (  )  [pure virtual]

Returns a valid external camera for the current time (to by pass the app for speed) You should use this call with extreme caution: It assumes nothing will be changed in the scene while you use the external interface. In particular, if the time is changed you should call this function to get a new pointer.

virtual boolean MCCOMAPI I3DShCamera::IsProjectionAffine ( void   )  const [pure virtual]

Returns true if the projection is affine (if w component from projection is always 1.0)

virtual boolean MCCOMAPI I3DShCamera::PreProject3DTo2D ( const TVector3 cameraPosition,
TVector4 projectedPosition 
) const [pure virtual]
Deprecated:
Do not implement this method.
virtual MCCOMErr MCCOMAPI I3DShCamera::Preset ( uint32  preset,
const TVector3 aimedPoint,
real  distance 
) [pure virtual]

Sends the camera to a reference position.

Parameters:
preset A present orientation (see ECameraPreset)
aimedPoint A target point for the camera
distance The distance from the camera to the point.
virtual boolean MCCOMAPI I3DShCamera::Project3DTo2D ( const TVector3 position,
TVector2 resultScreenPosition,
real resultDistanceToScreen 
) const [pure virtual]

Projects a point in camera coordinates on the screen.

Parameters:
position The point to project (in Camera Coordinates)
resultScreenPosition The projection on the screen.
resultDistanceToScreen The distance to the screen.
virtual MCCOMErr MCCOMAPI I3DShCamera::SetCameraComponent ( IShComponent cameraComponent,
ECloneMode  cloneMode 
) [pure virtual]

Sets the camera component.

Parameters:
cameraComponent A pointer to the camera component.
cloneMode The way the camera component should be changed (see ECloneMode)
virtual MCCOMErr MCCOMAPI I3DShCamera::SetCameraComponent ( int32  kindID  )  [pure virtual]

Sets the kind of this camera.

Parameters:
kindID The class ID of the camera.
virtual void MCCOMAPI I3DShCamera::SetCanonicalCameraType ( ECanonicalCameraType  canonicalCameraType,
real canonicalScale 
) [pure virtual]

Sets the type of camera when it is a canonical camera (see I3DEditorHostPart).

Parameters:
canonicalCameraType The type of camera (see ECanonicalCameraType).
canonicalScale The scale to apply to the position preset of canonical cameras (for others pass NULL)
virtual void MCCOMAPI I3DShCamera::SetProductionOffset ( const TVector2 inOffset  )  [pure virtual]

Sets the offset of the production frame.

Parameters:
inOffset The offsent in screen coordinates.
virtual void MCCOMAPI I3DShCamera::SetProductionZoom ( real  zoom  )  [pure virtual]

Sets the size of the production frame.

Parameters:
zoom The size of the production frame.
virtual void MCCOMAPI I3DShCamera::SetRenderingUVBox ( const TBBox2D inUVBox  )  [pure virtual]

Notifies the external camera of the screen coordinates bounding box that is going to be used during the rendering. The Camera should store that information and use it if needed in CreateRay/PreProject3DTo2D/Project3DTo2D So far only the spherical camera needs this

Parameters:
inUVBox The uvbox of the screen.

The documentation for this struct was generated from the following file:
Generated on Mon Apr 26 22:47:40 2010 for Carrara SDK Doc by  doxygen 1.6.3