Overriding subWorldDraw() and subViewportDraw()

AutoCAD ^® calls the worldDraw() and viewportDraw() functions to display the entity, which in turn call subWorldDraw() and subViewportDraw(), respectively, for specialized draw functionality. You must implement the subWorldDraw() function for any class derived from AcDbEntity. The subViewportDraw() function is optional.

virtual Adesk::Boolean
AcDbEntity::subWorldDraw(
    AcGiWorldDraw * pWd);
 
virtual void
AcDbEntity::subViewportDraw(
    AcGiViewportDraw * pVd);

Whenever AutoCAD needs to regenerate the graphics to display an entity, the worldDraw() and viewportDraw() functions are called in the following manner:

if (!entity->worldDraw(pWd))
    for (each relevant viewport)
        entity->viewportDraw(pVd);

The worldDraw() function calls subWorldDraw() to build the portion of the entity's graphical representation that can be specified independently of any particular model-space view or paper-space viewport contexts. The viewportDraw() function then calls subViewportDraw() to build the view-dependent portion of the entity's graphics. If any of the entity's graphics are view-dependent, the subWorldDraw() function must return kFalse and the subViewportDraw() function must be implemented. Conversely, if the entity has no view-dependent graphics, then the subWorldDraw() function must return kTrue, and the custom entity does not implement the subViewportDraw() function.

The AcDbEntity::subWorldDraw() function takes a pointer to an AcGiWorldDraw object. AcGiWorldDraw is a container class for the AcGi geometry and traits objects. Specifically, AcGiWorldDraw contains two other objects:

• AcGiWorldGeometry
• AcGiSubEntityTraits

The AcGiWorldGeometry object can be accessed from within the worldDraw() function by using the AcGiWorldDraw::geometry() function, and the AcGiSubEntityTraits object can be accessed by using the AcGiWorldDraw::subEntityTraits() function.

The AcGiWorldGeometry object writes vectors to AutoCAD's refresh memory using its set of drawing primitives. A primitive is the lowest-level instruction used to draw graphical entities. The world geometry object has the following functions for drawing primitives in world coordinates:

• Circle
• Circular arc
• Polyline
• Polygon
• Mesh
• Shell
• Text
• Xline
• Ray

The AcGiSubEntityTraits object sets graphical attribute values using the following set of traits functions:

• Color
• Layer
• Linetype
• Polygon fill type
• Selection marker

The AcDbEntity::subViewportDraw() function takes a pointer to an AcGiViewportDraw object and builds the view-specific representation of an entity. The viewport draw object is also a container object for other objects, which include the following:

• AcGiViewportGeometry
• AcGiSubEntityTraits
• AcGiViewport

The viewport geometry object provides the same list of primitives as the world geometry object and adds to it the following primitives, which use eye- and display-space coordinates to draw polylines and polygons:

• polylineEye()
• polygonEye()
• polylineDc()
• polygonDc()

The viewport subentity traits object is the same as that used by the world draw object (AcGiSubEntityTraits). The viewport object provides functions for querying the viewport's transformation matrices and viewing parameters.

Danger: An AcGi object such as AcGiWorldDraw or AcGiViewportDraw should not be stored as a global or static variable. Do not save copies of AcGi objects across calls to the worldDraw() and viewportDraw() functions. Once these functions return, the AcGi objects are no longer valid.

Danger: When a custom entity implements subWorldDraw() or subViewportDraw(), and if a native entity (e.g., AcDbCircle) is created within the scope of the method, the native entity needs to exist beyond the method’s scope. The variable should be declared in a global or class level, or some level where the object is alive even after exiting the method.

For more information about the AcGi library, see The Graphics Interface Library.