1. Advanced deepclone API in AutoCAD®
Cyrille Fauvel
Autodesk Developer Network
ADN Sparks Manager

2. Class Objective You learn We do not discuss and assume knowledge of
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
This is a class for programmers who already have some familiarity with both the .NET Framework, the AutoCAD .NET API and ObjectARX.
We will be looking at using the AutoCAD deepClone API to work programmatically with objects.

3. 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.
I have been working with AutoCAD APIs for over twenty years. A key part of my job is to support communication between external plug-in developers and our engineering to help the later create the APIs that the former need to write really cool add-in applications. I learned programming by myself, because when I was young and bought my first computer, I was short of money to buy games. So I had to wrote them myself ;) Now it is like an hobby, can’t get rid of it,

4. 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
Some of you may be unfamiliar with ADN. The Autodesk Developer Network is a program providing professional support to programmers writing add-in applications for Autodesk software. If you think the program benefits listed here would be useful to you, then visit this URL and read more about it. You don’t have to be a commercial software developer to join ADN.

5. Agenda 1 2 3 4 5 Overview Basics API A concrete example
Cloning! What is it? Why should I care? 2
Basics
Shallow Clone, deep Clone & wblock Clone
Who is using cloning? 3
API
Cloning and ID Translations
ObjectARX or .Net? 4
A concrete example
Modify the default AutoCAD behavior 5
Additional information
Inspect, spy, learning more

6. Overview Cloning! What is it? Why should I care?

7. 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.

8. 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

9. 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

10. 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

11. Basics Shallow Clone, Deep Clone & Wblock Clone Who is using cloning?

12. Cloning methods Shallow Cloning Deep Cloning Wblock 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

13. First user is AutoCAD AutoCAD uses deepClone and/or wblock
Copy operations
deepClone
Wblock operations
wblock
Insert operations
deepClone (insert)
Copy & Paste
Wblock & deepClone (insert)
Entity drag operation …

14. 'Ownership' and 'Pointer References'
4 types
Combination of [ Hard or Soft ] and [ Ownership or Pointer ]
Hard
Reference required for the object to survive in a database
Soft
Reference not required (can be ignored depending of the context)
Ownership
Parent – Child relation ship
Pointer
Cooperative object the object is referencing for its definition

15. References ObjectARX .Net No custom objects in .Net
AcDbHardOwnershipId
AcDbSoftOwnershipId
AcDbHardPointerId
AcDbSoftPointerId
.Net
ObjectId
No custom objects in .Net
Use overrules instead
Cloning reference logic follows reference found in the filing protocol
dwgInFields() / dwgOutFields()

16. Object ownership Object Object’ Ext. Dict. Hard Owner Soft Owner
Dictionary
Object
Dictionary
Object
Object
Object
Object
Hard Owner
Soft Owner
Hard Pointer
Soft Pointer

17. Entity ownership Entity Sub Entity Sub Entity Sub Entity Sub Entity
Hard Owner
Soft Owner
Hard Pointer
Soft Pointer

18. Can we get things more complicated? Entities are objects
Entity or BTR
Ext. Dict.
Sub Entity
Object’
Sub Entity
Object’
Ext. Dict.
Sub Entity
Object’
Sub Entity or Entity
Object’
Dictionary
Object
Dictionary
Ext. Dict.
Ext. Dict.
Ext. Dict.
Object
Object
Object
Object
Dictionary
Dictionary
Dictionary
Object
Object
Object
Dictionary
Dictionary
Dictionary
Hard Owner
Object
Object
Object
Object
Object
Object
Soft Owner
Object
Object
Object
Object
Object
Object
Hard Pointer
Soft Pointer

19. A DWG database DWG Block Tbl Layer Tbl … NOD BTR LTR … Dictionary BTR
Object
Dictionary
Entity
Entity
Object
Entity
Object
Entity
Object
Object
Hard Owner
Soft Owner
Hard Pointer
Soft Pointer

20. 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
deepClone will find & clone it
Wblock will find & clone it as well
The extension dictionary hard ‘owns’ its elements
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

21. Cloning phases Default cloning phase Application cloning phase
AutoCAD clones objects by following the ID references
Application cloning phase
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’

22. 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

23. 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

24. 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

25. 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()

26. API Cloning and ID Translations ObjectARX or .Net?

27. 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);

28. AcRxEventReactor / AcEditorReactor Autodesk. AutoCAD. DatabaseServices
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();

29. 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();

30. Custom objects ObjectARX Only API Sealed in ARX now 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;

31. Overrule API Overrules registered on per class basis Can ‘modify’
PEX protocol
See ‘CP230-1V - .Net Overrule API’ for details
Can ‘modify’
Draw aspect,
Grips,
Avoid the need of a custom object

32. Available overrules PropertiesOverrule DrawableOverrule OsnapOverrule
TransformOverrule
GripOverrule
SubentityOverrule
HighlightOverrule
GeometryOverrule
ObjectOverrule

33. 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);

34. A concrete example Modify the default AutoCAD behavior

35. ARXCloning sample CLONE1 command CLONE2 command CLONE3 command
Performs a shallow clone of a non-database resident object.
CLONE2 command
Performs a shallow clone of a database resident object into the same database
CLONE3 command
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.

36. OPLine project OPLine1 OPLine2 OPLine3
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

37. Bonus The deepClone Inspector tool
Monitors deepClone activity in AutoCAD
Record object status and cloning steps
Shows primary and secondary clones
Displays a diagram of the structures (original and clones)
Displays differences between the original and target databases

38. Additional information Inspect, spy, learning more

39. Learning more CP230-1V - .Net Overrule API CP240-2V
AutoCAD .NET: Practical Examples of Customizing AutoCAD Entity Behavior
Stephen Preston – Autodesk, Inc.

40. Learning more AutoCAD API
Online Help, Developer's Guide and SDK Samples
AutoCAD Developer Center Free DevTV for .NET API
Webcasts and Trainings on Programming and News > AutoCAD API
Through the Interface

41. Materials Handout Presentation Sample code and models
AU10_CP220-3C_ARX_Cloning_2011_API.docx
Presentation
AU10_CP220-3C_ARX_Cloning_2011_API.pptx
Sample code and models
AU10_CP220-3C_ARX_Cloning_2011_API.zip

42. Thank you! cyrille.fauvel@autodesk.com

43. 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.

44. DWG Block Tbl Layer Tbl … NOD BTR LTR … Dictionary BTR LTR … Object
Entity
Entity
Object
Entity
Object
Entity
Object
Object
Object
Entity
Object’
Ext. Dict.
Sub Entity
Sub Entity
Sub Entity
Sub Entity
Dictionary
Object
Dictionary
Hard Owner
Soft Owner
Object
Object
Object
Hard Pointer
Object
Soft Pointer