BaseView / BaseDraw Manual

Table of Contents

• About
• Access
• Update
• Properties
  • Rotation
  • Camera
  • Scene Elements
  • GPU Renderer
• Drawing
  • Drawing Pass
  • Parameters
  • Settings
  • Matrix
  • 2D Drawing Operations
  • General Drawing Operations
  • Objects
  • Line Strip
  • XOR Lines
  • Colors
  • Frame
  • Stereo
• Projection
  • Transformation
  • Testing and Clipping
• Undo
• Miscellaneous
• BaseDrawHelp
• Further Reading

About

A BaseView object represents a viewport window. Such a BaseView can be obtained from the active BaseDocument to get information on the viewport window. The class BaseDraw is based on BaseView. It can be used to draw something in a viewport window via a "Draw" function.

Warning

It is only allowed to draw into the viewport inside a "Draw" function. See Draw Manual.

Access

The BaseDraw windows used to display the active BaseDocument can be accessed with:

• BaseDocument::GetActiveBaseDraw(): Returns the BaseDraw of the currently active editor window.
• BaseDocument::GetRenderBaseDraw(): Returns the BaseDraw that should be used as the render view. This function should be used in NodeData based plugins.
• BaseDocument::GetBaseDrawCount(): Returns the number of current editor windows.
• BaseDocument::GetBaseDraw(): Returns the BaseDraw with the given index.
• BaseDocument::ForceCreateBaseDraw(): Called to enforce at least one BaseDraw is available.

See BaseDocument Editor Windows.

Such a BaseDraw can be used to access the scene camera.

  // This example accesses the active BaseDraw to get its camera.
  // Then it moves the active object into the view of that camera.
 
  BaseDraw* const baseDraw = doc->GetActiveBaseDraw();
  if (baseDraw == nullptr)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  BaseObject* const cameraObject = baseDraw->GetEditorCamera();
 
  // move active object into the camera view
  const Matrix cameraMatrix = cameraObject->GetMg();
  Matrix       targetPosition = activeObject->GetMg();
 
  targetPosition.off = cameraMatrix.off + (900.0 * cameraMatrix.sqmat.v3);
  activeObject->SetMg(targetPosition);

Update

The viewport windows are redrawn if something in the active document changed:

• EventAdd(): Informs Cinema 4D that something in the active document changed. DrawViews() will be called.
• DrawViews(): Manually triggers the scene execution and a viewport redraw. Typically only used directly in ToolData based tools.

See also Core Messages Manual and Cinema 4D Threads Manual.

Properties

The parameters of a given BaseDraw are accessed as usual with C4DAtom::GetParameter() and C4DAtom::SetParameter(). The parameter IDs are defined in dbasedraw.h

• BaseDraw::GetParameterData(): Convenience function to access parameters.

  // This example enables the display of polygon normals.
 
  baseDraw->SetParameter(ConstDescID(DescLevel(BASEDRAW_DATA_SHOWNORMALS)), true, DESCFLAGS_SET::NONE);
  baseDraw->SetParameter(ConstDescID(DescLevel(BASEDRAW_DATA_SELECTED_NORMALS)), false, DESCFLAGS_SET::NONE);
 
  // scale normal size
  const Float oldScale = baseDraw->GetParameterData(BASEDRAW_DATA_NORMALS_SCALE).GetFloat();
  const Float newScale = oldScale * 2.0;
  baseDraw->SetParameter(ConstDescID(DescLevel(BASEDRAW_DATA_NORMALS_SCALE)), newScale, DESCFLAGS_SET::NONE);

  // This example changes the projection type and display mode.
 
  const DescID projectionID = ConstDescID(DescLevel(BASEDRAW_DATA_PROJECTION));
  const Int32  projectionType = BASEDRAW_PROJECTION_FRONT;
  baseDraw->SetParameter(projectionID, projectionType, DESCFLAGS_SET::NONE);
 
  const DescID displayID = ConstDescID(DescLevel(BASEDRAW_DATA_SDISPLAYACTIVE));
  const Int32  displayType = BASEDRAW_SDISPLAY_HIDDENLINE;
  baseDraw->SetParameter(displayID, displayType, DESCFLAGS_SET::NONE);

A BaseDraw defines also certain display filters that decide what element types are displayed in the viewport windows.

• BaseDraw::GetDisplayFilter(): Returns a bitfield that stores the current display filters.

Note

To edit the filter settings use the parameters defined in dbasedraw.h

  // This example checks if the given BaseObject is visible in the active editor view.
 
  BaseDraw* const bd = doc->GetActiveBaseDraw();
  if (bd == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  const DISPLAYFILTER filter = bd->GetDisplayFilter();
  const Bool displayFilter = CheckDisplayFilter(object, filter);
 
  // check editor visibility
  const Bool editorVisibiliy = CheckEditorVisibility(object);
 
  // check if the object is visible in the viewport
  if (displayFilter && editorVisibiliy)
  {
    ApplicationOutput("The object is visible in the Editor"_s);
  }
  else
  {
    ApplicationOutput("The object is not visible in the Editor"_s);
  }

  // This example switches the filter setting
  // of the SDS filter.
 
  const DISPLAYFILTER filter = baseDraw->GetDisplayFilter();
 
  // switch filter for SDS
  if (filter & DISPLAYFILTER::HYPERNURBS)
    baseDraw->SetParameter(ConstDescID(DescLevel(BASEDRAW_DISPLAYFILTER_HYPERNURBS)), false, DESCFLAGS_SET::NONE);
  else
    baseDraw->SetParameter(ConstDescID(DescLevel(BASEDRAW_DISPLAYFILTER_HYPERNURBS)), true, DESCFLAGS_SET::NONE);

Rotation

A viewport window with planar projection can be rotated:

• BaseView::GetPlanarRotation(): Returns the rotation of a planar view.
• BaseView::SetPlanarRotation(): Sets the rotation of a planar view.

  // This example restores the rotation of all editor windows.
 
  const Int32 count = doc->GetBaseDrawCount();
 
  for (Int32 i = 0; i < count; ++i)
  {
    BaseDraw* const baseDraw = doc->GetBaseDraw(i);
    if (baseDraw == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    baseDraw->InitUndo(doc);
    baseDraw->SetPlanarRotation(0.0f);
  }

Camera

A viewport window with a perspective projection displays the scene from the point of view of a camera. This camera is defined using an object. This can be a scene camera, a scene object or the editor camera.

• BaseDraw::HasCameraLink(): Returns true if a scene object is used to define the BaseDraw.
• BaseDraw::GetSceneCamera(): Returns the linked scene camera or object.
• BaseDraw::GetEditorCamera(): Returns the default editor camera.
• BaseDraw::SetSceneCamera(): Sets the given BaseObject as the scene camera.
• BaseView::GetMg(): Returns the global camera matrix.
• BaseView::GetMi(): Returns the inverse of the global camera matrix.

See also CameraObject Manual.

  // This example accesses or sets the scene camera.
 
  // get the BaseDraw
  BaseDraw* const bd = doc->GetActiveBaseDraw();
  if (bd == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // check if a scene camera is used
  if (bd->HasCameraLink())
  {
    // get scene camera and print the name
    BaseObject* const cam = bd->GetSceneCamera(doc);
    if (cam != nullptr)
      ApplicationOutput("Camera Object: " + cam->GetName());
  }
  else
  {
    // create a new camera object
    BaseObject* const camera = BaseObject::Alloc(Ocamera);
    if (camera == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    doc->InsertObject(camera, nullptr, nullptr);
 
    // use this camera as the scene camera
    bd->SetSceneCamera(camera);
  }

Scene Elements

The viewport also displays a background and some global light settings. Both the background and the global seetings are defines using scene elements.

• BaseDraw::GetSkyObject(): Returns the used sky object.
• BaseDraw::GetEnvironmentObject(): Returns the used environment object.
• BaseDraw::GetBackgroundObject(): Returns the used background object.
• BaseDraw::GetForegroundObject(): Returs the used foreground object.

  // This example accesses the sky object and
  // environment object from the given BaseDraw.
 
  BaseObject* const envObject = baseDraw->GetEnvironmentObject();
  if (envObject)
  {
    GeData data;
    envObject->GetParameter(ConstDescID(DescLevel(ENVIRONMENT_AMBIENT)), data, DESCFLAGS_GET::NONE);
 
    const Vector color = data.GetVector();
    ApplicationOutput("Environment Color: " + String::VectorToString(color));
  }
 
  // check the used sky object
 
  BaseObject* const skyObject = baseDraw->GetSkyObject();
  if (skyObject)
  {
    BaseTag* const tag = skyObject->GetTag(Ttexture);
    if (tag)
    {
      GeData data;
      tag->GetParameter(ConstDescID(DescLevel(TEXTURETAG_MATERIAL)), data, DESCFLAGS_GET::NONE);
 
      C4DAtom*    const atom = data.GetLinkAtom(doc);
      BaseList2D* const material = static_cast<BaseList2D*>(atom);
 
      if (material)
        ApplicationOutput("Material on Sky: " + material->GetName());
    }
  }

GPU Renderer

The GPU renderer of Cinema 4D can render inside a given BaseDraw window.

• BaseDraw::IsMarkedAsGPURenderer(): Returns true if the BaseDraw is used as a GPU renderer view.
• BaseDraw::IsGPURenderer(): Returns true if the BaseDraw is running the GPU renderer.

Drawing

Inside a "Draw" function one can use the following functions to draw into the viewport windows. See Draw Manual.

Warning

It is not allowed to draw in any other context.

While drawing one should check if the drawing thread has been aborted:

• BaseDraw::TestBreak(): Returns true if the drawing operation should be aborted.

  // This example tests if the current drawing operation should be aborted.
 
  Bool Draw(BaseSceneHook* node, BaseDocument* doc, BaseDraw* bd, BaseDrawHelp* bh, BaseThread* bt, SCENEHOOKDRAW flags)
  {
    iferr_scope_handler
    {
      err.DiagOutput();
      err.DbgStop();
      return false;
    };
 
    // check if all pointers are valid
    if (node == nullptr || doc == nullptr || bd == nullptr || bh == nullptr)
      iferr_throw(maxon::NullptrError(MAXON_SOURCE_LOCATION));
 
    // check if the drawing operation should be aborted
    if (bd->TestBreak())
      return true;

Drawing Pass

The viewport is drawn in several passes. One should check if the drawing operation is needed in the current pass. This is especially important for ObjectData::Draw().

• BaseDraw::GetDrawPass(): Returns the current drawing pass:
  • DRAWPASS::OBJECT : Object pass.
  • DRAWPASS::BOX : Box pass.
  • DRAWPASS::HANDLES : Handle pass.
  • DRAWPASS::HIGHLIGHTS : Highlight pass.
  • DRAWPASS::XRAY : X-Ray pass.
• BaseDraw::AddToPostPass(): Adds the object to XRAY.

Parameters

Several parameters configure the drawing operations that follow.

• BaseDraw::GetDrawParam(): Returns the value of the given parameter.
• BaseDraw::SetDrawParam(): Sets the value of the given parameter.

The parameters are:

• DRAW_PARAMETER_LINEWIDTH: Line width in pixels.
• DRAW_PARAMETER_ALPHA_THRESHOLD: Alpha threshold between.
• DRAW_PARAMETER_SETZ: The Z-buffer mode. See DRAW_Z.
• DRAW_PARAMETER_OGL_CULLING: OpenGL culling. See DRAW_PARAMETER_OGL_CULLING.
• DRAW_PARAMETER_USE_Z: Use Z.
• DRAW_PARAMETER_OGL_PRIMITIVERESTARTINDEX: OpenGL primitive start index.

Note

At the end of the drawing operation these parameters have to be restored.

      // This example changes the line width, draws a line and resets the old value.
 
      // store and set line width
      const GeData oldLineWidth = bd->GetDrawParam(DRAW_PARAMETER_LINEWIDTH);
      bd->SetDrawParam(DRAW_PARAMETER_LINEWIDTH, GeData { 3.0 });
 
      // draw lines
      bd->SetPen(Vector { 1.0, 0.0, 0.0 });
      bd->DrawLine(Vector { 0, 0, 0 }, Vector { 100, 100, 0 }, NOCLIP_D);
 
      // reset parameter
      bd->SetDrawParam(DRAW_PARAMETER_LINEWIDTH, oldLineWidth);

Settings

The draw settings configure the drawing operations that follow.

• BaseDraw::SetPen(): Sets the pen color.
• BaseDraw::SetPointSize(): Sets the point size.

Note

The color used with BaseDraw::SetPen() may be obtained with GetViewColor(). See also Colors.

      // This example draws some points with random color and size.
 
      bd->SetMatrix_Matrix(nullptr, Matrix(), 6);
 
      Random rnd;
 
      for (Int32 i = 0; i < 100; ++i)
      {
        // set random color
        const Float  r = rnd.Get01();
        const Float  g = rnd.Get01();
        const Float  b = rnd.Get01();
        const Vector color { r, g, b };
        bd->SetPen(color);
 
        // set random size
        const Float size = rnd.Get01() * 10.0;
        bd->SetPointSize(size);
 
        // draw point with custom size
        const Vector pos { i* 10.0, 0.0, 0.0 };
        bd->DrawHandle(pos, DRAWHANDLE::CUSTOM, 0);
      }

The light list defines what lights should influence the shading on 3D drawing operations. Typically used to disable lights.

• BaseDraw::SetLightList(): Sets the lighting mode.
  • BDRAW_SETLIGHTLIST_NOLIGHTS: No lights.
  • BDRAW_SETLIGHTLIST_SCENELIGHTS: Scene lights.
  • BDRAW_SETLIGHTLIST_QUICKSHADING: Quick shading.

Transparency settings for polygon drawing are defined with:

• BaseDraw::GetTransparency(): Returns the transparency.
• BaseDraw::SetTransparency(): Sets the transparency.
• ::HIGHLIGHT_TRANSPARENCY: A special constant that sets the (yellowish) highlight transparency mode.

See also DRAW_PARAMETER_ALPHA_THRESHOLD above.

Matrix

A drawing operation may be performed in screen, camera or world space. Before any drawing operation the operation space must be defined.

• BaseDraw::SetMatrix_Screen(): Sets the transformation matrix to screen coordinates.
• BaseDraw::SetMatrix_Camera(): Sets the transformation matrix to the camera system.
• BaseDraw::SetMatrix_Matrix(): Sets the transformation matrix to the given Matrix.

      // This example draws some points in various spaces.
 
      // draw something in screen space
 
      const Vector screenPos { 100, 100.0, 0.0 };
 
      bd->SetMatrix_Screen();
      bd->DrawHandle(screenPos, DRAWHANDLE::BIG, 0);
 
      // draw something in camera space
 
      const Vector camPos { 0.0 };  // center of non-perspective camera
 
      bd->SetMatrix_Camera();
      bd->DrawHandle(camPos, DRAWHANDLE::BIG, 0);
 
      // draw something in world space
 
      const Vector worldPos { 100.0, 100.0, 100.0 };
 
      bd->SetMatrix_Matrix(nullptr, Matrix());
      bd->DrawHandle(worldPos, DRAWHANDLE::BIG, 0);

2D Drawing Operations

These functions perform drawing operations in 2D space:

• BaseDraw::DrawPoint2D(): Draws a 2D point.
• BaseDraw::DrawLine2D(): Draws a 2D line.
• BaseDraw::DrawHandle2D(): Draws a 2D handle.
• BaseDraw::DrawCircle2D(): Draws a 2D circle.

Note

To calculate screen space coordinates see Transformation.

      // This example draws a 2D line, circle and point.
 
      bd->SetMatrix_Screen();
 
      const Vector center { 100, 100, 0 };
      const Vector tangentPoint { 150, 100, 0 };
 
      // draw line and circle
      bd->SetPen(Vector(0.8));
      bd->DrawLine2D(center, tangentPoint);
      bd->DrawCircle2D((Int32)center.x, (Int32)center.y, tangentPoint.x - center.x);
 
      // draw point
      bd->SetPen(Vector(1.0));
      bd->DrawPoint2D(center);

Text can easily be drawn with:

• BaseDraw::DrawHUDText(): Draws some text in the viewport using the style of the HUD.
• BaseDraw::DrawMultipleHUDText(): Draws multiple texts in the viewport using the style of the HUD.
• HUDTextEntry: A text element that should be drawn in the viewport.

Note

These functions are typically used with a scene hook.

      // This example draws two text boxes in the viewport in a scene hook.
 
      const DRAWPASS pass = bd->GetDrawPass();
 
      // check if the current pass is the object pass with inverted highlight flag
      if ((flags& SCENEHOOKDRAW::HIGHLIGHT_PASS_INV) && pass == DRAWPASS::OBJECT)
      {
        bd->SetTransparency(0);
 
        maxon::BaseArray<HUDTextEntry> hudEntries;
 
        HUDTextEntry entryA;
        entryA._txt = "This is the first entry";
        entryA._position = Vector { 200, 220, 0 };
        hudEntries.Append(entryA) iferr_return;
 
        HUDTextEntry entryB;
        entryB._txt = "This is the second entry";
        entryB._position = Vector { 200, 260, 0 };
        hudEntries.Append(entryB) iferr_return;
 
        bd->DrawMultipleHUDText(hudEntries);
      }

General Drawing Operations

Depending on the current transformation matrix these operations can draw in 2D or 3D space.

The z-buffer is configured with:

• BaseDraw::LineZOffset(): Sets the current Z buffer offset.

These clipping flags used with 3D drawing operations:

• NOCLIP_D: Clip against the viewport window.
• NOCLIP_Z: Clip against near and far plane.

The drawing operations are:

• BaseDraw::DrawHandle(): Draws a handle.
• BaseDraw::DrawPointArray(): Draws a point array.
• BaseDraw::DrawLine(): Draws a line.
• BaseDraw::DrawArc(): Draws an arc.
• BaseDraw::DrawTexture(): Draws a given BaseBitmap. See BaseBitmap Manual.
• BaseDraw::DrawCircle(): Draws a circle.
• BaseDraw::DrawBox(): Draws a box.
• BaseDraw::DrawSphere(): Draws a sphere.
• BaseDraw::DrawPoly(): Draws a colored and shaded triangle or quadrangle.
• BaseDraw::DrawPolygon(): Draws a manually shaded triangle or quadrangle.
• BaseDraw::DrawBoundingBox(): Draws the bounding box of the given BaseObject.

      // This example fills a GeClipMap.
      // The internal BaseBitmap is used to draw the content to the screen.
 
      AutoAlloc<GeClipMap> clipMap;
      if (clipMap)
      {
        clipMap->Init(100, 50, 32);
        clipMap->BeginDraw();
        // fill background
        clipMap->SetColor(255, 0, 0, 64);
        clipMap->FillRect(0, 0, 100, 50);
        // draw text
        clipMap->SetColor(0, 0, 0, 255);
        clipMap->TextAt(0, 11, "Hello World");
 
        clipMap->EndDraw();
 
        const BaseBitmap* const bitmap = clipMap->GetBitmap();
 
        if (bitmap)
        {
          // draw texture in screen space
          bd->SetMatrix_Screen();
 
          const DRAW_ALPHA        alpha = DRAW_ALPHA::FROM_IMAGE;
          const DRAW_TEXTUREFLAGS texture = DRAW_TEXTUREFLAGS::NONE;
          bd->DrawTexture(bitmap, positions.GetFirst(), colors.GetFirst(), normals.GetFirst(), uvcoords.GetFirst(), 4, alpha, texture);
        }
      }

Each BaseDraw::DrawPolygon() puts the polygon into an internal array. The drawing of this array can be triggered with:

• BaseDraw::DrawArrayEnd(): Draws the stored polygon array.

A simple shading value is often used with BaseDraw::DrawPoly() and BaseDraw::DrawPolygon():

• BaseDraw::SimpleShade(): Returns the light intensity based on the given normal and light direction.

      // This example shades four vertices and uses the
      // calculated colors with BaseDraw::DrawPolygon().
 
      // base color
      const Vector color { 1.0, 0.0, 0.0 };
 
      // calculate shades
      colors[0] = color * bd->SimpleShade(vertice[0], normals[0]);
      colors[1] = color * bd->SimpleShade(vertice[1], normals[1]);
      colors[2] = color * bd->SimpleShade(vertice[2], normals[2]);
      colors[3] = color * bd->SimpleShade(vertice[3], normals[3]);
 
      // draw in object space
      const Matrix& mg = bh->GetMg();
      bd->SetMatrix_Matrix(op, mg);
 
      // no additional shading
      bd->SetLightList(BDRAW_SETLIGHTLIST_NOLIGHTS);
 
      // set transparency
      bd->SetTransparency(128);
 
      // draw polygon
      bd->DrawPolygon(vertice, colors, true);

Objects

Complete polygon objects can be drawn with:

• BaseDraw::DrawPolygonObject(): Draws the given polygon object.
• BaseDraw::DrawObject(): Draws the given object.

      // This example re-draws the currently active polygon object in a ObjectData::Draw() function.
 
      BaseDocument* const doc = bd->GetDocument();
 
      // check if the current pass is the object pass
      const Bool docSet = doc != nullptr;
      const Bool isObjectPass = drawpass == DRAWPASS::OBJECT;
 
      if (docSet && isObjectPass)
      {
        // get the active object
        BaseObject* const activeObject = doc->GetActiveObject();
 
        // check if the active object is not the host object itself
        // and if it is a polygon object
 
        const Bool activeObjectSet = activeObject != nullptr;
        const Bool activeObjectIsNotOp = activeObject != op;
 
        if (activeObjectSet && activeObjectIsNotOp)
        {
          if (activeObject->IsInstanceOf(Opolygon))
          {
            // draw the object
            bd->SetMatrix_Matrix(nullptr, Matrix());
            bd->DrawObject(bh, activeObject, DRAWOBJECT::NONE, drawpass, nullptr);
 
            return DRAWRESULT::OK;
          }
        }
      }

Line Strip

The line strip functions allow to easily draw line paths:

• BaseDraw::LineStripBegin(): Begins the line strip.
• BaseDraw::LineStrip(): Draws a line from the last point to the given point.
• BaseDraw::LineStripEnd(): Ends the line strip.

      // This example draws a random path composed of several lines.
 
      Random randomGen;
 
      // start position
      Vector pos(0);
 
      // init
      const GeData oldLineWidth = bd->GetDrawParam(DRAW_PARAMETER_LINEWIDTH);
      bd->SetDrawParam(DRAW_PARAMETER_LINEWIDTH, GeData { 4.0 });
      bd->SetMatrix_Matrix(nullptr, Matrix());
 
      // draw random lines
      bd->LineStripBegin();
 
      for (Int32 i = 0; i < 100; ++i)
      {
        // get random color
        const Float  r = randomGen.Get01();
        const Float  g = randomGen.Get01();
        const Float  b = randomGen.Get01();
        const Vector color { r, g, b };
 
        bd->LineStrip(pos, color, NOCLIP_Z);
 
        // apply random offset
        const Float x = randomGen.Get01() * 100;
        const Float y = randomGen.Get01() * 100;
        const Float z = randomGen.Get01() * 100;
 
        pos += Vector(x, y, z);
      }
 
      bd->LineStripEnd();
 
      // reset parameter
      bd->SetDrawParam(DRAW_PARAMETER_LINEWIDTH, oldLineWidth);

XOR Lines

XOR lines are used with selection tools in the viewport. Typically one should use the LassoSelection class instead.

Warning

These functions have been marked as deprecated.

• BaseDraw::InitDrawXORPolyLine(): Initiates XOR drawing.
• BaseDraw::BeginDrawXORPolyLine(): Starts drawing an XOR polygon line.
• BaseDraw::DrawXORPolyLine(): Draws an XOR polygon line.
• BaseDraw::EndDrawXORPolyLine(): Ends drawing an XOR polygon line.
• BaseDraw::FreeDrawXORPolyLine(): Ends XOR drawing.

See also EditorWindow::DrawXORLine().

        // This example draws a XOR line in ToolData::MouseInput().
 
        // check if the view can be initialized
        if (bd->InitDrawXORPolyLine())
        {
          bd->BeginDrawXORPolyLine();
 
          bd->DrawXORPolyLine(point, 2);
          bd->EndDrawXORPolyLine(true);
 
          bd->FreeDrawXORPolyLine();
 
          const DRAWFLAGS flags =
            DRAWFLAGS::NO_THREAD |
            DRAWFLAGS::INMOVE |
            DRAWFLAGS::ONLY_ACTIVE_VIEW |
            DRAWFLAGS::NO_ANIMATION;
 
          DrawViews(flags, bd);
        }
        else
        {
          win->DrawXORLine((Int32)point[0], (Int32)point[1], (Int32)point[2], (Int32)point[3]);
        }

Colors

Colors can be obtained and converted with:

• BaseDraw::ConvertColor(): Converts the given color from document color to viewport color profile.
• BaseDraw::ConvertColorReverse(): Converts the given color from viewport color to document color profile.
• BaseDraw::CheckColor(): Calculates the difference of the given color to VIEWCOLOR_C4DBACKGROUND and returns a color that is changed if needed.
• BaseDraw::GetObjectColor(): Returns the wireframe color of the given BaseObject.
• BaseDraw::GetHighlightPassColor(): Gets the color in which an object is drawn in the highlight pass.

      // This example gets the object color for the object itself in ObjectData::Draw().
      // This color is then used to draw a circle.
 
      const Vector color = bd->GetObjectColor(bh, op);
      bd->SetPen(color);
 
      bd->SetMatrix_Matrix(nullptr, Matrix());
 
      Matrix circleSettings = bh->GetMg();
      circleSettings.sqmat.v1 *= 200.0;
      circleSettings.sqmat.v2 *= 200.0;
      circleSettings.sqmat.v3 *= 200.0;
 
      bd->DrawCircle(circleSettings);

Frame

The dimensions of a viewport window are accessed with:

• BaseView::GetFrame(): Gets the frame dimensions in pixel.
• BaseView::GetSafeFrame(): Gets the dimensions of the safe frame.

  // This example prints the frame size of the given BaseDraw.
  // PrintFrameSize() is a custom utility function.
 
  Int32 cl, ct, cr, cb;
 
  // frame size
  baseDraw->GetFrame(&cl, &ct, &cr, &cb);
  PrintFrameSize(cl, ct, cr, cb);
 
  // safe frame
  baseDraw->GetSafeFrame(&cl, &ct, &cr, &cb);
  PrintFrameSize(cl, ct, cr, cb);

Stereo

These functions get and change the stereo settings for the given viewport window:

• BaseView::GetStereoInfo(): Returns the StereoCameraInfo data.
• BaseDraw::OverrideCamera(): Changes the stereoscopic camera data for this view.

Projection

A viewport window can display the scene using orthogonal or perspective projection:

• BaseDraw::GetViewMatrix(): Returns the requested view matrix, see DRAW_GET_VIEWMATRIX.
• BaseView::GetProjection(): Returns the projection type as defined in ocamera.h.
• BaseView::GetViewParameter(): Gets the parameters for the current projection.
• BaseView::GetBaseMatrix(): Returns the base matrix.
• BaseView::SetBaseMatrix(): Sets the base matrix.

Transformation

The following functions allow to transform a given point between world, screen and camera space:

• BaseView::WS(): Converts a world space point to screen space.
• BaseView::SW(): Converts a screen space point to world space.
• BaseView::SW_Reference(): Converts a screen space point to world space. The depth is based on the given argument.
• BaseView::WC(): Converts a world space point to camera space.
• BaseView::CW(): Converts a camera space point to world space.
• BaseView::SC(): Converts a screen space point to camera space.
• BaseView::CS(): Converts a camera space point to screen space.
• BaseView::WC_V(): Converts a world space vector to camera space.
• BaseView::CW_V(): Converts a camera space vector to world space.
• BaseView::WS_V(): Converts a world space vector to screen space.
• BaseView::SW_V(): Converts a screen space vector to world space.

      // This example draws a circle around the position of the active object.
 
      const BaseObject* const object = doc->GetActiveObject();
      if (object)
      {
        const Vector worldSpacePos  = object->GetMg().off;
        const Vector screenSpacePos = bd->WS(worldSpacePos);
 
        bd->DrawCircle2D((Int32)screenSpacePos.x, (Int32)screenSpacePos.y, 100);
      }

          // This example picks an object in the viewport within a ToolData:MouseInput() function.
          // The distance of the picked object is obtained from the C4DObjectList and used
          // with BaseView::SW() to get the world space position.
 
          const Int32 xpos = (Int32)x;
          const Int32 ypos = (Int32)y;
 
          Matrix4d64 m;
 
          const Bool res = ViewportSelect::PickObject(bd, doc, xpos, ypos, 1,
            VIEWPORT_PICK_FLAGS::NONE, nullptr, list, &m);
 
          if (res && (list->GetCount() > 0))
          {
            const Float  distance = list->GetZ(0);
            const Vector worldSpacePos = bd->SW(Vector(x, y, distance));
 
            ApplicationOutput("World Space Hit Point: " + String::VectorToString(worldSpacePos));
          }

Also sizes can be transformed:

• BaseView::PW_S(): Returns the size in world units for a single pixel at the given Z-depth.
• BaseView::WP_S(): Returns the size in pixels for a single world unit at the given Z-depth.
• BaseView::PW_W(): Returns the size in world units for a single pixel at the given screen space position.
• BaseView::WP_W(): Returns the size in screen space pixels for a single world unit at world position.

These 3D projection functions are typically used to handle mouse input in tools:

• BaseView::ProjectPointOnLine(): Returns the nearest point on the given line for a given mouse coordinate.
• BaseView::ProjectPointOnPlane(): Returns the nearest point on the given plane for a given mouse coordinate.

          // This example moves an object on the base plane in a ToolData::MouseInput() function.
 
          Int32        err = 0;
          const Vector pos = bd->ProjectPointOnPlane(Vector(0), Vector(0, 1, 0), positionX, positionY, &err);
          if (err == 0)
          {
            // place object
            Matrix mg = object->GetMg();
            mg.off = pos;
            object->SetMg(mg);
 
            // update managers and viewport
            GeSyncMessage(EVMSG_ASYNCEDITORMOVE, 0, 0, 0);
            DrawViews(DRAWFLAGS::ONLY_ACTIVE_VIEW | DRAWFLAGS::NO_THREAD | DRAWFLAGS::NO_ANIMATION);
          }

Testing and Clipping

The following tests can be performed:

• BaseDraw::PointInRange(): Returns true if the given screen space point is in hit range of the given world space point.
• BaseView::TestPoint(): Returns true if the given screen space point is visible.
• BaseView::TestPointZ(): Returns true if the given camera space point is visible.
• BaseView::TestClipping3D(): Returns true if the given bounding box is visible.
• BaseView::BackfaceCulling(): Returns true if the given face is visible.

        // This example draws a 2D circle for each point of the given polygon object.
        // The object is only handled if its bounding box is visible in the viewport.
        // A circle is only drawn if the point is inside the viewport window.
 
        // get polygon object properties
        const Matrix mg = polyObject->GetMg();
        const Vector bbox = polyObject->GetMp();
        const Vector rad  = polyObject->GetRad();
 
        // test if the poly object is visible at all
        if (bd->TestClipping3D(bbox, rad, mg, nullptr, nullptr))
        {
          // set pen color
          Vector color(0.6, 0.6, 0.6);
          color = bd->CheckColor(color);
          bd->SetPen(color);
 
          // points
          const Vector* const points = polyObject->GetPointR();
          const Int32         pointCount = polyObject->GetPointCount();
 
          // get each point
          for (Int32 i = 0; i < pointCount; ++i)
          {
            const Vector point = mg * points[i];
            const Vector screenSpacePos = bd->WS(point);
 
            // check each point
            if (bd->TestPoint(screenSpacePos.x, screenSpacePos.y))
            {
              // draw circle for each point
              bd->DrawCircle2D(SAFEINT32(screenSpacePos.x), SAFEINT32(screenSpacePos.y), 10.0f);
            }
          }
        }

A given line define by two points can be clipped:

• BaseView::ClipLine2D(): Clips the given line so that it fits within the view boundary.
• BaseView::ClipLineZ(): Clips the given line so that it does not come too close to or behind the camera.

A view can use near- and far-clipping:

• BaseView::ZSensitiveNear(): Returns true if the view has Z near-clipping.
• BaseView::ZSensitiveNearClipping(): Returns the near-clipping distance of the Z sensitive view.
• BaseView::ZSensitiveFar(): Returns true if the view has Z far-clipping.
• BaseView::ZSensitiveFarClipping(): Returns the far-clipping distance of the Z sensitive view.

Undo

A BaseDraw has its own undo buffer that stores changes:

• BaseDraw::InitUndo(): Stores the settings of the view in an undo buffer.
• BaseDraw::DoUndo(): Performs an undo operation.

  // This example restores the rotation of all editor windows.
 
  const Int32 count = doc->GetBaseDrawCount();
 
  for (Int32 i = 0; i < count; ++i)
  {
    BaseDraw* const baseDraw = doc->GetBaseDraw(i);
    if (baseDraw == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    baseDraw->InitUndo(doc);
    baseDraw->SetPlanarRotation(0.0f);
  }

Miscellaneous

Further functions are:

• BaseDraw::GetReductionMode(): Returns the used reduction mode, see ::DISPLAYMODE.
• BaseDraw::GetEditState(): Convenience function to check "Isoline Editing" and "Deformed Editing" viewport parameters. See ::DISPLAYEDITSTATE. For all parameters see Properties.
• BaseDraw::GetGridStep(): Gets the grid spacing and the transparency value.
• BaseDraw::IsViewOpen(): Returns true if the BaseDraw is open.
• BaseDraw::GetEditorWindow(): Returns the associated EditorWindow.
• BaseDraw::IsOpenGL(): Returns true if the BaseDraw is connected to the draw port.
• BaseDraw::GetDrawStatistics(): Gets a BaseContainer with OpenGL geometry statistics. See DRAW_STATISTIC.

  // This example accesses the Drawport statistics of the given BaseDraw
  // and prints them to the console window.
 
  // get draw statistics
  maxon::DataDictionary stats;
  if (!baseDraw->GetDrawStatistics(stats))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  for (const auto& data : stats)
  {
    const maxon::Data key = data.first.GetCopy() iferr_return;
    const maxon::Data value = data.second.GetCopy() iferr_return;
    const maxon::DataType type = value.GetType();
    ApplicationOutput("Key: @, Value: @ (@)", key, value, type);
  }

BaseDrawHelp

BaseDrawHelp is a utility class that contains useful information. It is mostly used in the context of ObjectData::Draw(). An instance is typically handed over as an argument but can also be created on demand:

• BaseDrawHelp::Alloc(): Creates a new BaseDrawHelp object.
• BaseDrawHelp::Free(): Deletes the given BaseDrawHelp object.

The BaseDrawHelp object provides access to these properties:

• BaseDrawHelp::GetDocument(): Returns the relevant BaseDocument.
• BaseDrawHelp::GetActiveTag(): Returns the active BaseTag.
• BaseDrawHelp::GetViewSchedulerFlags(): Returns the flags passed to DrawViews(), see ::DRAWFLAGS.

Information on the BaseObject that is supposed to be drawn:

• BaseDrawHelp::GetMg(): Returns the global matrix of the object.
• BaseDrawHelp::SetMg(): Sets the matrix returned by the above function.
• BaseDrawHelp::IsActive(): Returns true if the current object is active.
• BaseDrawHelp::IsHighlight(): Returns true if the current object is highlighted.

A BaseObject may be drawn with a specific display mode as defined in Tdisplay.h.

• BaseDrawHelp::GetDisplay(): Returns a container with the display mode.
• BaseDrawHelp::SetDisplay(): Sets the display mode for the object to be drawn.

        // This example draws a given polygon object using a BaseDrawHelp in ObjectData::Draw().
 
        // allocate BaseDrawHelp
        BaseDrawHelp* bhelp = BaseDrawHelp::Alloc(bd, bh->GetDocument());
        if (bhelp == nullptr)
          return DRAWRESULT::FAILURE;
 
        // get the current display options
        BaseContainer displayOptions = bh->GetDisplay();
 
        // set mode to "Wire"
        displayOptions.SetInt32(DISPLAYTAG_SDISPLAYMODE, (Int32)DISPLAYMODE::WIRE);
 
        // set display options
        bhelp->SetDisplay(&displayOptions);
 
        // get Matrix from original BaseDrawHelp object
        const Matrix originalMatrix = bh->GetMg();
        bhelp->SetMg(originalMatrix);
 
        // draw an object
        const DRAWOBJECT flags = DRAWOBJECT::USE_CUSTOM_COLOR | DRAWOBJECT::XRAY_OFF | DRAWOBJECT::NO_EOGL;
        bd->DrawObject(bhelp, object, flags, DRAWPASS::OBJECT, nullptr, Vector(1.0, 0, 0));
 
        // free BaseDrawHelp
        BaseDrawHelp::Free(bhelp);

Further Reading

• Draw Manual
• BaseDocument Manual
• Core Messages Manual
• Cinema 4D Threads Manual
• CameraObject Manual
• BaseBitmap Manual