# I3DShCamera Struct Reference
[Shell Interfaces]

Inheritance diagram for I3DShCamera:

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:

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

- I3dShCamera.h