I3DExCamera Struct Reference
[External Interfaces]

Inheritance diagram for I3DExCamera:
IMCUnknown TBasicCamera

List of all members.

Public Member Functions

virtual MCCOMErr MCCOMAPI SetTransform (const TTransform3D &transform)=0
virtual boolean MCCOMAPI CreateRay (const TVector2 &screenPosition, TVector3 &worldOrigin, TVector3 &worldDirection) const =0
virtual boolean MCCOMAPI CreateRay (const TVector2 &screenPosition, const TVector2 &screenDerivate, Ray3D &ray) const =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 &cameraPosition, TVector3 &screenPosition) const =0
virtual uint32 MCCOMAPI GetPrimitiveID () const =0
virtual void MCCOMAPI GetStandardCameraInfo (TStandardCameraInfo &cameraInfo) const =0
virtual MCCOMErr MCCOMAPI SetHalfWidth (real value)=0
virtual MCCOMErr MCCOMAPI SetNearPlane (real32 value)=0
virtual void MCCOMAPI SetRenderingUVBox (const TBBox2D &inUVBox)=0
virtual boolean MCCOMAPI InitDepthOfField (int32 &samplingQuality)=0
virtual boolean MCCOMAPI CreateRay (const TVector2 &screenPosition, const TVector2 &screenDerivate, const TVector2 &lensPosition, Ray3D &ray)=0
virtual real32 MCCOMAPI GetScalingFactor () const =0
virtual void MCCOMAPI SetScalingFactor (real32 inValue)=0

Detailed Description

Cameras define the projection from the 3D world to the 2D screen on which the image is rendered. There are two common forms of projection: orthographic and perspective. An orthographic camera takes rays parallel to the z-axis and projects them on the x-y plane by removing z.

A perspective camera takes all rays coming to a point and intersects those rays with a plane some distance from the point. The distance to this plane is the focal length. As with a real camera, it is possible to implement various lenses, focal values, zoom effects, etc. Projection is not restricted to the conical projection (the natural projection in your eye), so isometric or fish-eye cameras can be designed.

There are three basic methods. Project3DTo2D() is used to create the projection from 3D space onto the screen. This call is used by the hybrid raytracer. The two CreateRay() function calls create a 3D ray from a screen point. These calls are used for the ray-tracing. (You need to implement both CreateRay() calls.)

For your camera to be used by the interactive renderer, you must implement GetStandardCameraInfo(). For performance reasons, the interactive renderer requires a standard isometric or canonical camera. The parameters for this standard camera are supplied by GetStandardCameraInfo().

There are two interfaces to access a component: The shell interface (ISh. or I3DSh.) and the external interface (IEx. or I3DEx.)

The structure of a camera is a little bit more complex that the typical component: 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:
I3DShCamera

Member Function Documentation

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

Creates a ray for depth of field rendering. Note that you should call InitDepthOfField() first (and for every frame)

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).
lensPosition The position on the lens (in [0,1]x[0,1])
ray The ray that is returned.

Implemented in TBasicCamera.

virtual boolean MCCOMAPI I3DExCamera::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.

Implemented in TBasicCamera.

virtual boolean MCCOMAPI I3DExCamera::CreateRay ( const TVector2 screenPosition,
TVector3 worldOrigin,
TVector3 worldDirection 
) 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.
worldOrigin The origin of the ray that is returned.
worldDirection The direction of the ray that is returned.

Implemented in TBasicCamera.

virtual uint32 MCCOMAPI I3DExCamera::GetPrimitiveID (  )  const [pure virtual]

Returns an identificator for the camera.

Implemented in TBasicCamera.

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

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

virtual void MCCOMAPI I3DExCamera::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.

Implemented in TBasicCamera.

virtual boolean MCCOMAPI I3DExCamera::InitDepthOfField ( int32 &  samplingQuality  )  [pure virtual]

Inits the depth of field at the beginning of the rendering of a frame. Returns true if the camera has depth of field enabled.

Implemented in TBasicCamera.

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

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

Implemented in TBasicCamera.

virtual boolean MCCOMAPI I3DExCamera::PreProject3DTo2D ( const TVector3 cameraPosition,
TVector4 projectedPosition 
) const [pure virtual]
Deprecated:
Do not implement this method.

Implemented in TBasicCamera.

virtual boolean MCCOMAPI I3DExCamera::Project3DTo2D ( const TVector3 cameraPosition,
TVector3 screenPosition 
) const [pure virtual]

Projects a point on the screen.

Parameters:
cameraPosition The point to project on the screen. (in Camera Coordinates)
screenPosition The projection on the screen, the third coordinates is the z coordinates of the point in camera coordinates.
Returns:
true if the point has a projection on the screen, false otherwise.

Implemented in TBasicCamera.

virtual MCCOMErr MCCOMAPI I3DExCamera::SetHalfWidth ( real  value  )  [pure virtual]

Sets the half width of a camera (Used by modelers)

Implemented in TBasicCamera.

virtual MCCOMErr MCCOMAPI I3DExCamera::SetNearPlane ( real32  value  )  [pure virtual]

Sets the near clipping plane of the camera

Implemented in TBasicCamera.

virtual void MCCOMAPI I3DExCamera::SetRenderingUVBox ( const TBBox2D inUVBox  )  [pure virtual]

Notifies the 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 extent of the screen.

Implemented in TBasicCamera.

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

Sets the scaling factor of the object

Parameters:
inValue the number of inches to which the primitive's unit is equivalent
virtual MCCOMErr MCCOMAPI I3DExCamera::SetTransform ( const TTransform3D transform  )  [pure virtual]

Gives the camera its global transform. This can be used to create a cache to speed up the calculation in CreateRay for instance.

Parameters:
transform A reference to the Global Transform of the camera. You should not keep a pointer but copy it.

Implemented in TBasicCamera.


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