About

A CameraObject represents a camera in Cinema 4D. It is based on BaseObject (see BaseObject Manual).

CameraObject objects are an instance of Ocamera.

Access

A CameraObject is typically obtained from a BaseDraw representing a viewport window. This BaseDraw is obtained from the a BaseDocument.

BaseDraw::GetSceneCamera(): Returns the active scene camera.
BaseDraw::GetEditorCamera(): Returns the editor camera object.

See also BaseDocument Editor Windows.

  // This example gets the currently used camera.
 
  BaseDraw* const bd = doc->GetActiveBaseDraw();
  if (bd == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  BaseObject* camera = bd->GetSceneCamera(doc);
  if (camera == nullptr)
    camera = bd->GetEditorCamera();
 
  if (camera == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  ApplicationOutput("Camera name: @", maxon::String { camera->GetName() });
 

Note: Cinema 4D can use any object as a "camera" so the returned BaseObject may or may not be a CameraObject. One can check if it is a CameraObject with C4DAtom::IsInstanceOf().

Also a generator can contain a CameraObject. To get the real camera from that generator a message has to be sent to that generator:

MSG_GETREALCAMERADATA: Message ID sent to get a real camera object from a generator. The corresponding data is GetRealCameraData.
GetRealCameraData::res: The real camera object provided by the generator.

  // This example tries to get the internal camera from a generator.
  // Typically used with the Alembic Generator camera.
 
  GetRealCameraData data;
 
  // send the message to the object to get the "real camera"
  // and check the result
  if (obj->Message(MSG_GETREALCAMERADATA, &data) && data.res)
    obj = data.res;
 
  ApplicationOutput("Camera: @", maxon::String { obj->GetName() });

Allocation/Deallocation

CameraObject objects are created with the usual tools:

CameraObject::Alloc(): Creates a new CameraObject.
CameraObject::Free(): Deletes the given CameraObject.

A new or existing camera can be set as the active scene camera:

BaseDraw::SetSceneCamera(): Sets the given BaseObject as the used scene camera.

  // This example creates a new camera object and uses it as the scene camera.
 
  CameraObject* const camera = CameraObject::Alloc();
  if (camera == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->InsertObject(camera, nullptr, nullptr);
 
  camera->SetName("The new camera"_s);
 
  const Matrix mg = MatrixMove(Vector(0, 0, -500));
  camera->SetMg(mg);
 
  BaseDraw* const bd = doc->GetActiveBaseDraw();
  if (bd)
    bd->SetSceneCamera(camera);
 

Properties

The parameters of a CameraObject are edited as usual with C4DAtom::GetParameter() and C4DAtom::SetParameter(). The parameter IDs are defined in Ocamera.h.

Warning: Some parameters of the camera are "virtual" (CAMERAOBJECT_FOV and CAMERAOBJECT_FOV_VERTICAL) and cannot be accessed in any situation.

For some parameters dedicated functions exist.

Projection

These functions access the camera projection setting:

CameraObject::GetProjection(): Returns the camera projection setting.
CameraObject::SetProjection(): Sets the camera projection setting.

  // This example sets the projection of the selected camera object to "Parallel".
 
  BaseObject* const obj = doc->GetActiveObject();
 
  // the function needs a selected camera to get executed
  if (obj == nullptr || !obj->IsInstanceOf(Ocamera))
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  CameraObject* const camera = static_cast<CameraObject*>(obj);
 
  camera->SetProjection(Pparallel);

Zoom

These functions set the camera zoom value:

CameraObject::GetZoom(): Returns the camera zoom value.
CameraObject::SetZoom(): Sets the camera zoom value.

Offset

These functions set the camera position. This is the midpoint for orthogonal projections (Front/Back/Top/Bottom etc.).

CameraObject::GetOffset(): Returns the camera position.
CameraObject::SetOffset(): Sets the camera position.

Note: This is the same as setting the position with BaseObject::SetAbsPos().

Aperture

These functions set the camera aperture value:

CameraObject::GetAperture(): Returns the aperture width of the camera.
CameraObject::SetAperture(): Sets the aperture width of the camera.

Focus

These functions set the camera focus value:

CameraObject::GetFocus(): Returns the camera focus.
CameraObject::SetFocus(): Sets the camera focus.

Stereoscopic Camera

A CameraObject can also store information about the stereoscopic cameras it represents.

CameraObject::StereoGetCameraCount(): Returns the number of stereo cameras.
CameraObject::StereoGetCameraInfo(): Gets stereo camera information.

The stereo camera information is stored in a StereoCameraInfo structure object:

StereoCameraInfo::m: Matrix of the stereoscopic camera.
StereoCameraInfo::off_x: Stereoscopic camera film X offset.
StereoCameraInfo::off_y: Stereoscopic camera film Y offset.
StereoCameraInfo::strName: Name of the stereoscopic camera.

  // This example loops through the stereo cameras of the given camera object.
 
  CameraObject* const camera = static_cast<CameraObject*>(obj);
  RenderData*   const renderData = doc->GetActiveRenderData();
  BaseDraw*     const bd = doc->GetActiveBaseDraw();
  if (bd == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  const Int32 stereoCount = camera->StereoGetCameraCount(doc, bd, renderData, 0);
 
  for (Int32 i = 0; i < stereoCount; ++i)
  {
    StereoCameraInfo info;
    camera->StereoGetCameraInfo(doc, bd, renderData, i, info, 0);
 
    ApplicationOutput("Stereo Camera name: @", maxon::String { info.strName });
  }

Table of Contents