HOOPS Exchange 2025 to 2026 Migration Guide 
============================================

This guide covers all breaking changes and migration steps required when
upgrading from HOOPS Exchange 2025.x.y to 2026.1.0.

.. contents:: Table of Contents
   :depth: 2
   :local:


Renamed Header File
--------------------

The header ``A3DDisableFunctions.h`` has been renamed to ``A3DSDKDisableFunctions.h``.
Update your ``#include`` directives:

.. code-block:: c

   /* Before */
   #include <A3DDisableFunctions.h>

   /* After */
   #include <A3DSDKDisableFunctions.h>


Product Name: ProE → Creo, Unigraphics → NX
-------------------------------------------

All public symbols referencing the legacy product names "ProE" and "Unigraphics" have been renamed to "Creo" and "NX" respectively.
This affects structs, struct fields, functions, macros, and enum values.

Structs
^^^^^^^

.. list-table::
   :header-rows: 1

   * - Old Name
     - New Name
   * - ``A3DRWParamsProEData``
     - ``A3DRWParamsCreoData``
   * - ``A3DRWParamsUnigraphicsData``
     - ``A3DRWParamsNXData``
   * - ``A3DAsmProductOccurrenceDataProe``
     - ``A3DAsmProductOccurrenceDataCreo``
   * - ``A3DAsmProductOccurrenceDataUg``
     - ``A3DAsmProductOccurrenceDataNX``
   * - ``A3DPromotedBodyUg``
     - ``A3DPromotedBodyNX``
   * - ``A3DElementsByRefsetUg``
     - ``A3DElementsByRefsetNX``

Struct fields in ``A3DRWParamsSpecificLoadData``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: c

   /* Before */
   sLoadParams.m_sSpecifics.m_sProE;
   sLoadParams.m_sSpecifics.m_sUnigraphics;

   /* After */
   sLoadParams.m_sSpecifics.m_sCreo;
   sLoadParams.m_sSpecifics.m_sNX;

Struct fields in ``A3DAsmProductOccurrenceDataCreo``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The fields ``m_iProEMemberType`` and ``m_iProEMemberId`` are renamed to ``m_iCreoMemberType`` and ``m_iCreoMemberId`` respectively.

Functions
^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Old Name
     - New Name
   * - ``A3DAsmProductOccurrenceGetProe``
     - ``A3DAsmProductOccurrenceGetCreo``
   * - ``A3DAsmProductOccurrenceGetUg``
     - ``A3DAsmProductOccurrenceGetNX``

Initialization and check macros
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Old Macro
     - New Macro
   * - ``A3D_INITIALIZE_A3DRWParamsProEData``
     - ``A3D_INITIALIZE_A3DRWParamsCreoData``
   * - ``A3D_INITIALIZE_A3DRWParamsUnigraphicsData``
     - ``A3D_INITIALIZE_A3DRWParamsNXData``
   * - ``A3D_CHECKFILLED_A3DRWParamsProEData``
     - ``A3D_CHECKFILLED_A3DRWParamsCreoData``
   * - ``A3D_CHECKFILLED_A3DRWParamsUnigraphicsData``
     - ``A3D_CHECKFILLED_A3DRWParamsNXData``
   * - ``A3D_INITIALIZE_A3DAsmProductOccurrenceDataProe``
     - ``A3D_INITIALIZE_A3DAsmProductOccurrenceDataCreo``
   * - ``A3D_INITIALIZE_A3DAsmProductOccurrenceDataUg``
     - ``A3D_INITIALIZE_A3DAsmProductOccurrenceDataNX``

Enum types
^^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Old Type
     - New Type
   * - ``A3DProESessionColorType``
     - ``A3DECreoSessionColorType``
   * - ``A3DProEReadConstructEntities``
     - ``A3DECreoReadConstructEntities``
   * - ``A3DProEFamilyTables``
     - ``A3DECreoFamilyTables``

Enum values
^^^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Old Value
     - New Value
   * - ``kA3DModellerProE``
     - ``kA3DModellerCreo``
   * - ``kA3DModellerUnigraphics``
     - ``kA3DModellerNX``
   * - ``A3DProEReadConstructEntities_AsDatum``
     - ``kA3DCreoReadConstructEntities_AsDatum``
   * - ``A3DProEReadConstructEntities_Yes``
     - ``kA3DCreoReadConstructEntities_Yes``
   * - ``A3DProEReadConstructEntities_No``
     - ``kA3DCreoReadConstructEntities_No``
   * - ``A3DProEFamTabAcceleratorFileOnly``
     - ``kA3DCreoFamTabAcceleratorFileOnly``
   * - ``A3DProEFamTabOrUseTessellation``
     - ``kA3DCreoFamTabOrUseTessellation``
   * - ``A3DProEFamTabOrUseWireAndGeneric``
     - ``kA3DCreoFamTabOrUseWireAndGeneric``


SolidWorks Struct Renames
-------------------------

The SolidWorks attachment info struct and its referencing fields have been renamed to fix a typo:

.. list-table::
   :header-rows: 1

   * - Old Name
     - New Name
   * - ``A3DAsmAttachmentsInfosSLW``
     - ``A3DAsmAttachmentInfoSLW``

In ``A3DAsmProductOccurrenceDataSLW``:

.. code-block:: c

   /* Before */
   data.m_uiAttachementsSize;
   data.m_psAttachements;  /* type: A3DAsmAttachmentsInfosSLW* */

   /* After */
   data.m_uiAttachmentsSize;
   data.m_psAttachments;   /* type: A3DAsmAttachmentInfoSLW* */


Enum Naming Convention Harmonization
------------------------------------

A large number of enum types and values have been renamed to follow a consistent naming convention.
The old prefixes ``EA3D``, ``KEA3D``, ``KA3D``, and ``A3DE`` (on values) have been normalized.

Enum Type Renames
^^^^^^^^^^^^^^^^^

Enum types previously using the ``EA3D`` prefix now use ``A3DE``:

.. list-table::
   :header-rows: 1

   * - Old Type
     - New Type
   * - ``EA3DMDLineWeldingType``
     - ``A3DEMDLineWeldingType``
   * - ``EA3DGDTType``
     - ``A3DEGDTType``
   * - ``EA3DMarkupFrameType``
     - ``A3DEMarkupFrameType``
   * - ``EA3DLeaderAlignmentType``
     - ``A3DELeaderAlignmentType``
   * - ``EA3DMDRoughnessType``
     - ``A3DEMDRoughnessType``
   * - ``EA3DMDBalloonShape``
     - ``A3DEMDBalloonShape``
   * - ``EA3DLocatorSymbol``
     - ``A3DELocatorSymbol``
   * - ``EA3DLocatorType``
     - ``A3DELocatorType``
   * - ``EA3DMDAnchorPointType``
     - ``A3DEMDAnchorPointType``
   * - ``EA3DMDDimensionType``
     - ``A3DEMDDimensionType``
   * - ``EA3DMDDimensionValueOption``
     - ``A3DEMDDimensionValueOption``
   * - ``EA3DMDTextPropertiesFormat``
     - ``A3DEMDTextPropertiesFormat``
   * - ``EA3DFCFIndicatorType``
     - ``A3DEFCFIndicatorType``
   * - ``EA3DRevitPhysicalProperties``
     - ``A3DERevitPhysicalProperties``
   * - ``EA3DRevitLinks``
     - ``A3DERevitLinks``
   * - ``EA3DRevitMultiThreadedMode``
     - ``A3DERevitMultiThreadedMode``

This pattern applies to all ``EA3DFRM*`` types (Feature Recognition Module), all ``EA3DMDDimension*``, ``EA3DMDLineWelding*``, ``EA3DMDSpotWeld*``, ``EA3DLocator*``, and ``EA3DMDTextProperties*`` types.
Each ``EA3D`` prefix becomes ``A3DE``.

Other Type Renames
""""""""""""""""""

.. list-table::
   :header-rows: 1

   * - Old Type
     - New Type
   * - ``A3DMaterialPhysicType``
     - ``A3DEMaterialPhysicType``
   * - ``A3DCollisionType``
     - ``A3DECollisionType``
   * - ``A3DMDLeaderSymbolType``
     - ``A3DEMDLeaderSymbolType``
   * - ``A3DMDGDTValueType``
     - ``A3DEMDGDTValueType``


Enum Value Renames
^^^^^^^^^^^^^^^^^^

Enum values across markup, PMI, welding, tolerance, dimension, symbol, and feature modules have been renamed.
The general patterns are:

- ``KEA3D*`` → ``kA3D*`` (e.g. ``KEA3DGDTTypeNone`` → ``kA3DGDTTypeNone``)
- ``KA3D*`` → ``kA3D*`` (e.g. ``KA3DMarkupFrameNone`` → ``kA3DMarkupFrameNone``)
- ``A3DE*`` (values) → ``kA3D*`` (e.g. ``A3DPhysicType_None`` → ``kA3DPhysicType_None``)
- ``KEA3DSymbol_*`` → ``kA3DSymbol_*``
- ``KEA3DDimensionSymbolType*`` → ``kA3DDimensionSymbolType*``

**Typo fix in dimension symbol:** ``KEA3DDimensionSymbolTypeUNKNOW`` has been corrected to ``kA3DDimensionSymbolTypeUNKNOWN``.

ProductOccurrence Type Values
"""""""""""""""""""""""""""""

All format-specific product occurrence type values changed prefix from ``A3DE`` to ``kA3D``:

.. code-block:: c

   /* Before */
   A3DEProductOccurrenceTypeCat_model
   A3DEProductOccurrenceTypeInv_ipt
   A3DEProductOccurrenceTypeSLW_part

   /* After */
   kA3DProductOccurrenceTypeCat_model
   kA3DProductOccurrenceTypeInv_ipt
   kA3DProductOccurrenceTypeSLW_part

Texture Alpha Mode Values
"""""""""""""""""""""""""

.. code-block:: c

   /* Before */
   A3DETextureAlphaModeNone
   A3DETextureAlphaModeOpaque
   A3DETextureAlphaModeMask
   A3DETextureAlphaModeBlend

   /* After */
   kA3DTextureAlphaModeNone
   kA3DTextureAlphaModeOpaque
   kA3DTextureAlphaModeMask
   kA3DTextureAlphaModeBlend

Parasolid Translate Enum Values
"""""""""""""""""""""""""""""""

The ``kA3DE_`` prefix becomes ``kA3D_`` for healing, accuracy, simplify, merge, and JT version enums:

.. code-block:: c

   /* Before */
   kA3DE_HEALING_YES
   kA3DE_ACCURATE_ONLY_IF_NOT_PARASOLID
   kA3DE_JT100

   /* After */
   kA3D_HEALING_YES
   kA3D_ACCURATE_ONLY_IF_NOT_PARASOLID
   kA3D_JT100


Removed Deprecated Struct Fields
--------------------------------

The following struct fields, which were marked deprecated in 2025, have been removed.
Code referencing these fields will no longer compile.

.. list-table::
   :header-rows: 1

   * - Struct
     - Removed Field
     - Notes
   * - ``A3DRWParamsTessellationData``
     - ``deprecated_m_dMinimalTriangleAngleDeg``
     - No longer used.
   * - ``A3DRWParamsGeneralData``
     - ``deprecated_m_iNbMultiProcess``
     - No longer used.
   * - ``A3DRWParamsIGESData``
     - ``deprecated_m_bSewBrepModels``
     - Use ``A3DAsmModelFileSew`` instead.
   * - ``A3DAsmProductOccurrenceDataJT``
     - ``deprecated_m_usValidDisplayFields``
     - No longer used.
   * - ``A3DAsmLayerData`` (was ``A3DAsmLayer``)
     - ``deprecated_m_usLayer``
     - Use ``m_uiLayerID`` instead.

.. note::

   Removing fields changes the struct size.
   Recompile all code that initializes these structs with ``A3D_INITIALIZE_DATA``.


Removed Deprecated Enum Value
------------------------------

``deprecated_kA3DTessLODControlledPrecision`` has been removed from ``A3DETessellationLevelOfDetail``. 
Use ``kA3DTessLODExtraHigh`` or configure tessellation parameters directly using ``A3DRWParamsTessellationData::m_dAngleToleranceDeg`` and ``A3DRWParamsTessellationData::m_dMaxChordHeight``.

``deprecated_kA3DStepAP242`` has been removed from ``A3DEStepFormat``. 
Use ``kA3DStepAP242_Ed1`` instead.


Layer API Overhaul
------------------

The layer API has been significantly reworked.
Layers are now first-class entities (``A3DAsmLayer``) stored on ``A3DAsmProductOccurrenceData``, rather than being queried through a flat list API.

Struct Changes
^^^^^^^^^^^^^^

The old ``A3DAsmLayer`` struct (which was a plain data struct without ``m_usStructSize``) has been replaced by ``A3DAsmLayerData`` — a proper entity data struct with ``m_usStructSize``.

.. code-block:: c

   /* Before: A3DAsmLayer had no m_usStructSize field */
   A3DAsmLayer layer;

   /* After: A3DAsmLayerData follows standard initialization pattern */
   A3DAsmLayerData layer_data;
   A3D_INITIALIZE_DATA(A3DAsmLayerData, layer_data);

Function Changes
^^^^^^^^^^^^^^^^

.. code-block:: c

   /* Before */
   A3DAsmProductOccurrenceGetLayerList(pPO, &uiCount, &pLayers);

   /* After: iterate m_ppLayers from A3DAsmProductOccurrenceData, then: */
   A3DAsmLayerData layer_data;
   A3D_INITIALIZE_DATA(A3DAsmLayerData, layer_data);
   A3DAsmLayerGet(pLayer, &layer_data);


Renamed Struct: ``A3DRiComputeMeshDataParameters``
--------------------------------------------------

.. code-block:: c

   /* Before */
   A3DRiComputeMeshDataParameters params;
   A3D_INITIALIZE_DATA(A3DRiComputeMeshDataParameters, params);

   /* After */
   A3DRiComputeMeshParametersData params;
   A3D_INITIALIZE_DATA(A3DRiComputeMeshParametersData, params);

This also affects ``A3DRiComputeMesh`` and ``A3DTreeNodeGetGeometry`` which take this struct as a parameter.


Renamed Function: ``A3DAsmGetFilesPathFromModelFile``
-----------------------------------------------------

.. code-block:: c

   /* Before */
   A3DAsmGetFilesPathFromModelFile(pModelFile, &uiCount, &ppPaths);

   /* After */
   A3DAsmComputeFilePathsFromModelFile(pModelFile, &uiCount, &ppPaths);


Typo Fix: ``kA3DFontStreched``
------------------------------

The macro ``kA3DFontStreched`` has been corrected to ``kA3DFontStretched``.


Removed Deprecated Functions
-----------------------------

All functions that were prefixed with ``deprecated_`` in 2025 have been removed. 
The following table lists the most commonly used ones and their replacements:

Geometry and Tessellation
^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Removed Function
     - Replacement
   * - ``deprecated_A3DGetCurveAsAnalytic``
     - ``A3DSimplifyCurveWithAnalytics``
   * - ``deprecated_A3DGetCurveAsAnalyticFromCoEdge``
     - ``A3DSimplifyCurveWithAnalyticsFromCoEdge``
   * - ``deprecated_A3DGetSurfaceAsAnalytic``
     - ``A3DSimplifySurfaceWithAnalytics``
   * - ``deprecated_A3DSurfBaseGetAsNurbs``
     - ``A3DSurfBaseWithDomainGetAsNurbs``
   * - ``deprecated_A3DSimplifyModelFileCurveAndSurfaceAsAnalytic``
     - ``A3DSimplifyModelFileWithAnalytics``

Tools
^^^^^

.. list-table::
   :header-rows: 1

   * - Removed Function
     - Replacement
   * - ``deprecated_A3DProjectPointCloud2``
     - ``A3DProjectPointCloud3``
   * - ``deprecated_A3DComputeOrthoHLROnModelFile``
     - ``A3DComputeOrthoHLROnModelFile3``
   * - ``deprecated_A3DComputeOrthoHLROnModelFile2``
     - ``A3DComputeOrthoHLROnModelFile3``

Structure
^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Removed Function
     - Replacement
   * - ``deprecated_A3DAsmProductOccurrenceUnload``
     - ``A3DAsmModelFileUnloadParts``
   * - ``deprecated_A3DAsmPartDefinitionFeatureTreesGet``
     - Use ``A3DFRMTree`` from ``A3DAsmProductOccurrenceData``

Signal Handling
^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Removed Function
     - Replacement
   * - ``deprecated_A3DDisableHandleSIGSEGV``
     - None (default behavior since 11.2).
   * - ``deprecated_A3DEnableHandleSIGSEGV``
     - None (default behavior since 11.2).

RTF Markup
^^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Removed Function
     - Replacement
   * - ``deprecated_A3DMkpRTFInit``
     - ``A3DMkpRTFFieldCreate``
   * - ``deprecated_A3DMkpRTFGetField``
     - ``A3DMkpRTFFieldGet``
   * - ``deprecated_A3DMkpRTFDelete``
     - ``A3DMkpRTFFieldDelete``

The associated struct ``deprecated_A3DRTFFieldData`` has also been removed.
Use ``A3DMkpRTFFieldData`` instead.


Removed Deprecated PDF Functions
---------------------------------

All ``deprecated_A3DPDF*`` functions have been removed, including:

- ``deprecated_A3DPDFInitializePDFLib`` — use ``A3DPDFInitializePDFLibAndResourceDirectory``
- ``deprecated_A3DPDFDocumentCreateUniquePage`` and variants
- ``deprecated_A3DPDFDocumentAppendNewPage``
- ``deprecated_A3DPDFDocumentAppendPageFromPDFFile``
- ``deprecated_A3DPDFDocumentGetUniquePage``
- ``deprecated_A3DPDFDocumentSetPassword``
- ``deprecated_A3DPDFDocumentSetDocumentPermissions``
- ``deprecated_A3DPDFDocumentSave``
- ``deprecated_A3DPDFImageCreate``
- ``deprecated_A3DPDFPageInsertImage``
- ``deprecated_A3DPDFDefineViewCarousel``
- ``deprecated_A3DPDF3DArtworkCreate``
- ``deprecated_A3DPDFAnimMotionCreate``
- ``deprecated_A3DPDFDocumentAddImageAsIcon``
- ``deprecated_A3DPDFTableCreate``
- ``deprecated_A3DPDFDefineSlideTable`` and ``deprecated_A3DPDFDefineSlideTable2``
- ``deprecated_A3DPDFSlideTableLinkTo3DNodes``
- ``A3DPDFPageRemoveTable``
- ``A3DGetLicenseKey``

Use the non-deprecated equivalents available since earlier releases.


Removed Deprecated Draw Module
-------------------------------

The entire deprecated Draw module has been removed from the public API, including:

- ``deprecated_A3DDrawCallbacksData`` struct
- ``deprecated_A3DDrawInitCallbacks``
- ``deprecated_A3DDraw``
- ``deprecated_A3DDrawRepresentationItem``
- ``deprecated_A3DDrawMarkup``
- ``deprecated_A3DDrawGetBoundingBox``
- ``deprecated_kA3DDraw3D``, ``deprecated_kA3DDrawMarkups``
- All ``deprecated_A3DCallbackDraw*`` callback typedefs
- ``deprecated_A3DEDrawMaterialType`` enum


Removed Error Codes
-------------------

The following PDF error codes have been removed:

- ``A3DPDF_CANNOT_LOAD_TABLETOPDF_DLL`` (-1000021)
- ``A3DPDF_HTML_TABLE_ERROR`` (-1000022)
- ``A3DPDF_HTML_STYLE_ERROR`` (-1000023)


Newly Deprecated Functions
--------------------------

The following functions are now deprecated and will be removed in a future release.
They still compile but will emit deprecation warnings:

- ``A3DDllActivateXMLTrace`` — use XML tracing through initialization parameters.
- ``A3DXmlParsing``
- ``A3DAsmModelFileDelete`` — use ``A3DEntityDelete`` instead.
- ``A3DGraphicsDelete`` — use ``A3DEntityDelete`` instead.
- ``A3DMiscCascadedAttributesDelete`` — use ``A3DEntityDelete`` instead.

.. note::

   The ``m_ucBehaviour`` field in ``A3DAsmProductOccurrenceData`` is now deprecated and will be removed in version 2027.1.0.

