Advanced deepclone API in AutoCAD®
Cyrille Fauvel
Autodesk Developer Network
ADN Sparks Manager
Class Objective

You learn

AutoCAD deepClone API and cloning techniques
 Benchmarks, performance and implementation considerations
 Aspects of controlling cloning operations in AutoCAD

We do not discuss and assume knowledge of

How to program in .NET or ObjectARX
 The basics of the AutoCAD .Net or ObjectARX API
 AutoCAD product usage
About the Presenter
Cyrille Fauvel
Autodesk Developer Network
Cyrille is a member of the M&E workgroup of the Autodesk Developer Network (ADN)
team, providing developer support, training, and conference presentations on
AutoCAD, RealDWG, Inventor, Maya, 3ds Max, FBX API.
He joined Autodesk in 1994 as an AutoCAD developer based in Switzerland and
California, USA. Later moved to the Developer Support group, and Consulting division.
Cyrille graduated in Mechanics and Electronics in France, worked as a teacher and
C++ developer for a 3rd party developer on AutoCAD. He is fluent in six programming
languages, tries to learn Japanese which turns out to be more difficult than learning
English, has two kids, plays the guitar and piano, likes reading, love sailing on oceans,
sports, and especially hand-ball.
Autodesk Developer Network

Access to almost all Autodesk software and SDK’s





Includes early access to beta software
Members-only website with thousands of technical articles
Unlimited technical support
Product direction through conferences
Marketing benefits

Exposure on autodesk.com
 Promotional opportunities

One to three free API training classes

Based on user level
www.autodesk.com/joinadn
Agenda
Overview
1
Cloning! What is it?
Why should I care?
Basics
2
Shallow Clone, deep Clone & wblock Clone
Who is using cloning?
API
3
4
5
Cloning and ID Translations
ObjectARX or .Net?
A concrete example
Modify the default AutoCAD behavior
Additional information
Inspect, spy, learning more
Overview
Cloning! What is it?
Why should I care?
Cloning

Cloning in biology is the process of producing similar populations of
genetically identical individuals that occurs in nature when organisms
such as bacteria, insects or plants reproduce asexually. Cloning in
biotechnology refers to processes used to create copies of DNA
fragments (molecular cloning), cells (cell cloning), or organisms. The
term also refers to the production of multiple copies of a product such as
digital media or software.
 The term clone is derived from κλῶνος, the Greek word for "trunk,
branch", referring to the process whereby a new plant can be created
from a twig. In horticulture, the spelling clon was used until the twentieth
century; the final e came into use to indicate the vowel is a "long o"
instead of a "short o". Since the term entered the popular lexicon in a
more general context, the spelling clone has been used exclusively.
Cloning (disambiguation)

Cloning is the process of making an identical copy of something.

Cloning may also refer to:

Cloning (programming), the copying of a programming object
Disk cloning, the copying of the contents of a computer hard disk to a
storage medium or file
Phone cloning, the transfer of identity between one mobile telephone
and another
Reduplication, aka "cloning", in linguistics refers to a process by which
the root or stem of a word is repeated
Molecular cloning, the process of identifying and isolating a specific
gene




Cloning

Clone is not Copy

For this presentation

Clone = make a new instance of an object which has the same
property’ values of the original object

Copy = copy the value of an object property
First user is AutoCAD

AutoCAD uses deepClone and/or wblock









Copy, Mirror, Array operations
Wblock operations
Insert operations
Explode operation
Copy & Paste
Entity drag operation
Reference editing
…
Any other plug-ins which want to control cloning operations to:

Prevent clones
 Make sure objects required for a clone will be present


Maintain the integrity of a user defined structure across AutoCAD commands
…
Basics
Shallow Clone, Deep Clone & Wblock Clone
Who is using cloning?
Cloning methods

Shallow Cloning

Copy of a singleton ObjectARX C++ object
 AcRxObject::clone()



RTTI and C++ object copy
copyFrom() to copy properties
Deep Cloning

clones an object and its hard/soft ownership references
 but do not clone hard/soft pointer referenced objects
 however, copies the pointer reference values

Wblock Cloning

clones an object and its hard owner and hard pointer references
 but ignores any soft references
 and reset non cloned references to null
First user is AutoCAD

AutoCAD uses deepClone and/or wblock

Copy operations


Wblock operations


Wblock & deepClone (insert)
Entity drag operation


deepClone (insert)
Copy & Paste


wblock
Insert operations


deepClone
deepClone
…
'Ownership' and 'Pointer References'

4 types


Hard


Reference not required (can be ignored depending of the context)
Ownership


Reference required for the object to survive in a database
Soft


Combination of [ Hard or Soft ] and [ Ownership or Pointer ]
Parent – Child relation ship
Pointer

Cooperative object the object is referencing for its definition
References

ObjectARX

AcDbHardOwnershipId
 AcDbSoftOwnershipId
 AcDbHardPointerId
 AcDbSoftPointerId

.Net


No custom objects in .Net


ObjectId
Use overrules instead
Cloning reference logic follows reference found in the filing
protocol

dwgInFields() / dwgOutFields()
Object ownership
Object
Object’
Ext. Dict.
Dictionary
Object
Dictionary
Object
Object
Object
Object
Hard Owner
Soft Owner
Hard Pointer
Soft Pointer
Entity ownership
Entity
Sub
Entity
Sub
Entity
Sub
SubEntity
Entity
Hard Owner
Soft Owner
Hard Pointer
Soft Pointer
Can we get things more complicated?
Entities are objects
Object’
Ext. Dict.
Dictionary
Object
Dictionary
Object
Object
Object
Object
Hard Owner
Soft Owner
Hard Pointer
Soft Pointer
Entity
or BTR
Ext. Dict.
Sub
Entity
Sub
Entity
Sub
SubEntity
Entity
Object’
Object’
Object’
Object’
or Entity
Ext. Dict.
Ext. Dict.
Ext. Dict.
Dictionary
Object
Dictionary
Dictionary
Object
Dictionary
Dictionary
Object
Dictionary
Object
Object
Object
Object
Object
Object
Object
Object
Object
Object
Object
Object
A DWG database
Block Tbl
BTR
BTR
Entity
Entity
Entity
Entity
Hard Owner
Soft Owner
Hard Pointer
Soft Pointer
DWG
Layer Tbl
LTR
LTR
…
…
…
NOD
Dictionary
Object
Dictionary
Object
Object
Object
Object
Extension dictionary

Using extension dictionary can simplify a lot cloning operations,
because:

The object hard ‘owns’ it extension dictionary versus having to
reference an object in the NOD



The extension dictionary hard ‘owns’ its elements



deepClone will find & clone it
Wblock will find & clone it as well
deepClone will clone its elements
Wblock will clone them as well
Sounds a good solution to avoid to think about cloning. Well
consider the following:

Each DWG object is about ~300b footprint
 An object with an extension dictionary and an 1 object in it is ~ 1k
 Make a DWG 3 times bigger with no useful data in yet
Cloning phases

Default cloning phase


Application cloning phase


AutoCAD clones objects by following the ID references
AutoCAD may give control to a plug-in to do additional cloning and will
follow the ID references as required
ID translation phase

AutoCAD translate clone IDs to new ID & handles for object in ‘Flux’
In Flux

Clones in ‘Flux’ mode, means object being cloned, versus
created and mapped to an original object

Requires ID translation

You cannot intervene during this ID translation process process

Use the AcRxEventReactor class for monitoring activities and
steps
Primary object

If the key object is part of the primary set of objects cloned

An object can tell if it's being cloned by referencing or not

That's what the isPrimary flag is all about
Cloning contexts











kDcCopy / _COPY, _MIRROR, _ARRAY, Drag’n Drop
kDcExplode / _EXPLODE
kDcBlock / _BLOCK
kDcXrefBind / _XREF, _-BIND
kDcSymTableMerge / _IGESIN, _DXFIN, _XREF, _-ATTACH
kDcInsert / _INSERT, _PASTECLIP, Drag’n Drop
kDcWblock / _WBLOCK, _COPYCLIP, _DXFOUT
kDcObjects / _BLOCK, _REFEDIT, _REFCLOSE
kDcXrefInsert / _XREF _-INSERT
kDcInsertCopy
kDcWblkObjects / _REFEDIT, _REFCLOSE
AcDbObject::deepClone()
AcDbObject::wblockClone()

Never use AcDbObject::deepClone() or
AcDbObject::wblockClone() directly

You are missing the context
 But you can call them in custom object implementation or reactors

Instead use

Within the same database


AcDbDatabase::deepCloneObjects()
Across databases

AcDbDatabase::wblockCloneObjects()
 AcDbDatabase::wblock()
 AcDbDatabase::insert()

API
Cloning and ID Translations
ObjectARX or .Net?
AcDbDatabase
Autodesk.AutoCAD.DatabaseServices.Database


ObjectARX and .Net
Use these to start a cloning operation











void abortDeepClone(AcDbIdMapping&);
Acad::ErrorStatus deepCloneObjects(AcDbObjectIdArray&, AcDbObjectId&, AcDbIdMapping&, bool);
void forceWblockDatabaseCopy();
Acad::ErrorStatus insert(AcDbObjectId&, const ACHAR*, AcDbDatabase*, bool);
Acad::ErrorStatus insert(AcDbObjectId&, const ACHAR*, const ACHAR*, AcDbDatabase*, bool);
Acad::ErrorStatus insert(const AcGeMatrix3d&, AcDbDatabase*, bool);
Acad::ErrorStatus wblock(AcDbDatabase*&);
Acad::ErrorStatus wblock(AcDbDatabase*&, AcDbObjectId);
Acad::ErrorStatus wblock(AcDbDatabase*&, const AcDbObjectIdArray&, const AcGePoint3d&);
Acad::ErrorStatus wblock AcDbDatabase*, const AcDbObjectIdArray&, const AcGePoint3d&,
AcDb::DuplicateRecordCloning);
Acad::ErrorStatus wblockCloneObjects(AcDbObjectIdArray&, AcDbObjectId&, AcDbIdMapping&,
AcDb::DuplicateRecordCloning, bool);
AcRxEventReactor / AcEditorReactor
Autodesk.AutoCAD.DatabaseServices.Database

ObjectARX and .Net

















void beginDeepClone(AcDbDatabase*, AcDbIdMapping&);
void beginWblockObjects(AcDbDatabase*, AcDbIdMapping&);
void beginInsert(AcDbDatabase*, const AcGeMatrix3d&, AcDbDatabase*);
void beginInsert(AcDbDatabase*, const ACHAR *, AcDbDatabase*);
void beginWblock(AcDbDatabase*, AcDbDatabase*);
void beginWblock(AcDbDatabase*, AcDbDatabase*, AcDbObjectId);
void beginWblock(AcDbDatabase*, AcDbDatabase*, const AcGePoint3d*&);
void wblockNotice(AcDbDatabase*);
void otherInsert(AcDbDatabase*, AcDbIdMapping&, AcDbDatabase*);
void otherWblock(AcDbDatabase*, AcDbIdMapping&, AcDbDatabase*);
void beginDeepCloneXlation(AcDbIdMapping&, Acad::ErrorStatus*);
void endDeepClone(AcDbIdMapping&);
void endWblock(AcDbDatabase*);
void abortDeepClone(AcDbIdMapping&);
void abortWblock(AcDbDatabase*);
void abortInsert(AcDbDatabase*);
Acad::ErrorStatus veto();
RefEdit

RefEdit uses the wblock() mechanism

Checkout
 Checkin


Only modified objects will be clones in checkin
See the AcApLongTransactionReactor class






void beginCheckOut(AcDbLongTransaction&, AcDbObjectIdArray&);
void endCheckOut(AcDbLongTransaction&);
void beginCheckIn(AcDbLongTransaction&);
void endCheckIn(AcDbLongTransaction&);
void abortLongTransaction(AcDbLongTransaction&);
Acad::ErrorStatus veto();
Custom objects

ObjectARX Only

AcDbObject
 Autodesk.AutoCAD.DatabaseServices.DBObject



.Net implements these method, but you cannot override them
You can call them in a cloning context/operation
API Sealed in ARX now



Acad::ErrorStatus deepClone(AcDbObject*, AcDbObject*&, AcDbIdMapping&,
Adesk::Boolean) const;
Acad::ErrorStatus wblockClone(AcRxObject*, AcDbObject*&, AcDbIdMapping&,
Adesk::Boolean) const;
Use the subXXX() version instead


Acad::ErrorStatus subDeepClone(AcDbObject*, AcDbObject*&, AcDbIdMapping&,
Adesk::Boolean) const;
Acad::ErrorStatus subWblockClone(AcRxObject*, AcDbObject*&, AcDbIdMapping&,
Adesk::Boolean) const;
Overrule API


Overrules registered on per class basis

PEX protocol

See ‘CP230-1V - .Net Overrule API’ for details
Can ‘modify’

Draw aspect,
 Grips,

Avoid the need of a custom object
Available overrules

PropertiesOverrule
DrawableOverrule
OsnapOverrule
TransformOverrule
GripOverrule
SubentityOverrule
HighlightOverrule
GeometryOverrule

ObjectOverrule







Overrule API

ObjectARX and .Net

AcDbObjectOverrule



Acad::ErrorStatus deepClone(const AcDbObject*, AcDbObject*, AcDbObject*&,
AcDbIdMapping&, Adesk::Boolean);
Acad::ErrorStatus wblockClone(const AcDbObject*, AcRxObject*, AcDbObject*&,
AcDbIdMapping&, Adesk::Boolean);
Autodesk.AutoCAD.DatabaseServices.ObjectOverrule


DBObject DeepClone(DBObject, DBObject, IdMapping, [MarshalAs(UnmanagedType.U1)] bool);
DBObject WblockClone(DBObject, RXObject, IdMapping, [MarshalAs(UnmanagedType.U1)] bool);
A concrete example
Modify the default AutoCAD behavior
ARXCloning sample

CLONE1 command


CLONE2 command


Performs a shallow clone of a database resident object into the same
database
CLONE3 command


Performs a shallow clone of a non-database resident object.
Performs a shallow clone of a database resident object to another
DWG database
Very basic code one simple object such as a line or circle.
OPLine project

OPLine1

Custom entity derived from AcDbPolyline
 And a companion custom object derived from AcDdBObject stored in
the NOD

OPLine2


Try to replicate the above structure without custom object but using
reactors instead
OPLine3

Same but using the new overrule API
Additional information
Inspect, spy, learning more
Learning more


CP230-1V - .Net Overrule API
CP240-2V

AutoCAD .NET: Practical Examples of Customizing AutoCAD
Entity Behavior
Stephen Preston – Autodesk, Inc.
Learning more AutoCAD API

Online Help, Developer's Guide and SDK Samples

AutoCAD Developer Center
http://www.autodesk.com/developautocad
Free DevTV for .NET API

Webcasts and Trainings on Programming and News
http://www.adskconsulting.com/adn/cs/api_course_sched.php > AutoCAD API

Through the Interface
http://through-the-interface.typepad.com
Materials

Handout


Presentation


AU10_CP220-3C_ARX_Cloning_2011_API.docx
AU10_CP220-3C_ARX_Cloning_2011_API.pptx
Sample code and models

AU10_CP220-3C_ARX_Cloning_2011_API.zip
Thank you!
cyrille.fauvel@autodesk.com
Autodesk [and other] are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and/or other countries. All other brand names, product names, or trademarks belong to
their respective holders. Autodesk reserves the right to alter product and services offerings, and specifications and pricing at any time without notice, and is not responsible for typographical or graphical errors that may
appear in this document. © 2010 Autodesk, Inc. All rights reserved.
Block Tbl
BTR
BTR
DWG
Layer Tbl
LTR
LTR
…
…
…
Entity
Entity
Entity
Entity
Object
Object’
Hard Owner
Soft Owner
Hard Pointer
Soft Pointer
Ext. Dict.
Dictionary
Object
Dictionary
Object
Object
Object
Object
Entity
Sub
Entity
Sub
Entity
Sub
SubEntity
Entity
NOD
Dictionary
Object
Dictionary
Object
Object
Object
Object