I3DShCamera Struct Reference
[Shell Interfaces]

Inheritance diagram for I3DShCamera:


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)=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:

The Camera Instance that supports I3DShCamera, I3DShInstance and I3DShTreeElement.
The Camera Component that supports IShComponent, IExCamera and I3DShTreeElementMember

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.

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 ) [pure virtual]

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

Parameters:

canonicalCameraType The type of camera (see ECanonicalCameraType).

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:

I3dShCamera.h

Generated on Mon Mar 14 12:29:01 2005 for Carrara SDK Doc by

1.3.9.1

I3DShCamera Struct Reference [Shell Interfaces]

Public Member Functions

Detailed Description

Member Function Documentation

I3DShCamera Struct Reference
[Shell Interfaces]