I3DExCamera Struct Reference
[External Interfaces]

Inheritance diagram for I3DExCamera:

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 void MCCOMAPI	SetRenderingUVBox (const TBBox2D &inUVBox)=0
virtual boolean MCCOMAPI	InitDepthOfField ()=0
virtual boolean MCCOMAPI	CreateRay (const TVector2 &screenPosition, const TVector2 &screenDerivate, const TVector2 &lensPosition, Ray3D &ray)=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:

• 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:

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 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 (   )  [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 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 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:

• I3dExCamera.h

---