Draw Manual

Table of Contents

• About
• Draw
  • Usage
• Examples
• Further Reading

About

Many Cinema API plugin classes can implement a "Draw" function that allows to draw something in the editor viewport. These "Draw" functions differ from class to class.

Draw

A "Draw" function can be found in the following Cinema API base classes:

• ObjectData::Draw(): Is called for each object plugin instance.
• TagData::Draw(): Is called for each tag plugin instance.
• ToolData::Draw(): Is called for the tool plugin.
• SceneHookData::Draw(): Is called for the SceneHook plugin.
• MaterialData::Draw(): Is called for every object/tag pair that uses the material plugin instance.
• ShaderData::Draw(): Is called for each shader plugin instance.
• SnapData::Draw(): Is called for the snap mode plugin.

Note

To avoid drawing order problems the drawing operations of multiple objects or tags can be replaced by the use of the "Draw" function in a SceneHookData plugin.

Usage

A "Draw" function is typically called multiple times during the drawing process for different draw passes and for each open viewport window. The given BaseDraw object represents a viewport window and is used to draw in that window.

This is an example implementation of ObjectData::Draw():

  DRAWRESULT Draw(BaseObject* op, DRAWPASS drawpass, BaseDraw* bd, BaseDrawHelp* bh)
  {
    // only draw in the DRAWPASS_OBJECT
    if (drawpass != DRAWPASS_OBJECT)
      return SUPER::Draw(op, drawpass, bd, bh);
 
    // set the matrix / space for the following drawing operations
    // in this case, use the object's matrix
    const Matrix& mg = bh->GetMg();
    bd->SetMatrix_Matrix(op, mg);
 
    // set line width
    const GeData oldValue = 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(-100, 0, 0), Vector(100, 0, 0), NOCLIP_D);
 
    bd->SetPen(Vector(00, 1.0, 0.0));
    bd->DrawLine(Vector(0, 100, 0), Vector(0, -100, 0), NOCLIP_D);
 
    bd->SetPen(Vector(0.0, 0.0, 1.0));
    bd->DrawLine(Vector(0, 0, 100), Vector(0, 0, -100), NOCLIP_D);
 
    // reset parameters
    bd->SetDrawParam(DRAW_PARAMETER_LINEWIDTH, oldValue);
 
    return SUPER::Draw(op, drawpass, bd, bh);
  }

Typical tasks in a "Draw" function are:

• Check the current draw pass to avoid unnecessary operations.
• Check if the assigned layer of the object, tag or material disables viewport drawing.
• Set the reference coordinate system for the following drawing operations.
• Set the drawing parameters for the following drawing operations.
• Perform drawing operations.
• Reset the drawing parameters.

How to use a BaseDraw object is described in BaseView / BaseDraw Manual.

Examples

For objects that can be assigned to layers it might be necessary to check if the assigned layer forbids viewport drawing. See Layer Manual.

      // check if the assigned layer disables drawing
 
      BaseDocument*    doc = bh->GetDocument();
      const LayerData* ld  = op->GetLayerData(doc);
 
      // check if not visible in the editor
      if (ld && (!ld->view))
        return DRAWRESULT::SKIP;

If the drawing operations should only be applied to the currently selected viewport window it is needed to check if the given BaseDraw represents the selected viewport.

      // This example checks if the current BaseDraw is the active BaseDraw.
 
      BaseDraw*  const activeBD = doc->GetActiveBaseDraw();
      const Bool       isActiveBD = bd && (bd == activeBD);
 
      if (!isActiveBD)
        return DRAWRESULT::SKIP;

It is also possible to enable or disable several viewport filters that define what should be visible in the viewport.

      // This example checks if "Null" objects should be drawn in the viewport.
      // If not, the drawing is skipped.
 
      // check display filter for "Null" objects
      if (!(bd->GetDisplayFilter() & DISPLAYFILTER::NONE))
        return DRAWRESULT::SKIP;

Further Reading

• General Plugin Functionality Overview
• BaseView / BaseDraw Manual