:orphan:

##########
USD Writer
##########

.. rst-class:: format-title-block

+-----------------------------------------------------------------------------------------------------------+
|                           **Universal Scene Description (USD)**                                           |
+-----------------------------------------+-----------------------------------------------------------------+
| **File Extension**                      | .usd, .usda                                                     |
+-----------------------------------------+-----------------------------------------------------------------+
| **Supported Versions**                  | Any                                                             |
+-----------------------------------------+-----------------------------------------------------------------+
| :ref:`usd_wt_platforms`                 | |wy| |ly| |mn| |an| |in|                                        |
+-----------------------------------------+-----------------------------------------------------------------+
| :ref:`usd_wt_tessellation`              | |c_green| Supported                                             |
+-----------------------------------------+-----------------------------------------------------------------+
| **B-rep**                               | |c_grey| N/A                                                    |
+-----------------------------------------+-----------------------------------------------------------------+
| **PMI**                                 | |c_grey| N/A                                                    |
+-----------------------------------------+-----------------------------------------------------------------+

USD (Universal Scene Description) is an open-source format developed by Pixar for describing and exchanging complex 3D scenes.  
It supports hierarchical scene structure, geometry, materials, and metadata, and is widely adopted in visual effects, animation, and real-time simulation.

HOOPS Exchange now includes experimental support for exporting CAD data to USD, enabling early-stage interoperability with USD-based pipelines.

How to Export to USD
====================

.. sidebar::

   The USD writer is provided as an experimental feature.  
   For more details, see :ref:`ext_experimental_api`.

Because it's experimental, a few extra steps are needed to enable USD export.

.. _usd_writer_download:

1. Download the Exporter Library
--------------------------------

USD export is available via an additional library, which must be integrated into your HOOPS Exchange installation along with its dependencies.

Download it from `the Downloads page <https://developer.techsoft3d.com/hoops/exchange/downloads/latest>`__.  
Scroll to the *Related Technologies* section and choose *Experimental USD Writer*.

.. image:: usd_download.png

After downloading, extract the archive in the **same directory** where HOOPS Exchange was originally unpacked.  
This ensures the new libraries are placed in the correct folder structure.

Refer to :ref:`usd_wt_package` for a detailed breakdown of the package contents.

2. Enable Experimental Features
-------------------------------

To enable experimental functionality, define the macro ``A3DAPI_EXPERIMENTAL`` in your project.  
You can add it either as a compiler option or directly in your source code before including the HOOPS Exchange headers:

.. code-block:: c

   #define A3DAPI_EXPERIMENTAL
   #include <A3DSDKIncludes.h>

Ensure this macro is defined in any source file that loads the library or uses the USD exporter.

3. Use the Exporter
-------------------

To export a model to USD format, use the function :cpp:func:`A3DAsmModelFileExportToUSDFile`.  
Use the format-specific structure :cpp:struct:`A3DRWParamsExportUSDData` to configure the export process.

.. code-block:: c

   #define A3DAPI_EXPERIMENTAL
   #include <A3DSDKIncludes.h>

   // ...

   A3DRWParamsExportUSDData sParamsExportData = A3D_MAKE_DATA(A3DRWParamsExportUSDData);
   // ... set export parameter options

   A3DAsmModelFileExportToUSDFile(pModelFile, &sParamsExportData, "path/to/file.usd");

.. _usd_wt_tessellation:

Tessellation
============

The USD writer supports exporting tessellated geometry.

By default, the tessellation detail level is set to *medium* via :cpp:enum:`A3DETessellationLevelOfDetail`.  
You can adjust this by modifying the :cpp:member:`~A3DRWParamsExportUSDData::m_eTessellationLevelOfDetail` member in the export parameters.

.. _usd_wt_sample:

Extending the Import Export Sample
==================================

The C/C++ :ref:`sample_import_export` project can be extended to support USD export.

After downloading the writer binaries (see :ref:`USD writer download section <usd_writer_download>`), add the following definition at the **top** of *ImportExport.cpp*:

.. code-block:: c

   #define A3DAPI_EXPERIMENTAL

**GNU/Linux** users must also set the ``LD_LIBRARY_PATH`` environment variable to point to the *experimental_usd_writer/* directory.

To export, choose an output file with a *.usd* or *.usda* extension — the sample will then perform the export automatically.

To explore the sample further, see our tutorial: :doc:`file-to-file translation </tutorials/c/file-to-file-translation>`.

.. _usd_wt_platforms:

Supported Platforms
===================

As an experimental feature, the USD writer currently supports a subset of our regular :ref:`platforms_c_cpp_support`:

+-------------------+----------------------------+---------------------------+----------------------------+
| Platform          | Architecture               | Runtime Environment       | Compiler                   |
+===================+============================+===========================+============================+
| **Windows**       | x64                        | Windows 10                | MSVC v142                  |
+-------------------+----------------------------+---------------------------+----------------------------+
| **Linux**         | x64                        | | glibc 2.35              | GCC 11.4.0                 |
|                   |                            | | libstdc++.so.6.0        |                            |
+-------------------+----------------------------+---------------------------+----------------------------+

.. _usd_wt_package:

Package Description
===================

Here’s a breakdown of the extracted package contents:

.. tabs::

   .. tab:: Windows (MSVC)

      ======================================================================= ========================================================= 
       Folder/File     Description                                              
      ======================================================================= ========================================================= 
       readme_experimental_USDwriter.txt                                       How-to file
       **bin/win64_v142/experimental_usd_writer/**                             Binaries folder
       bin/win64_v142/experimental_usd_writer/experimental_wusd.dll            Main library file
       **bin/win64_v142/experimental_usd_writer/\*.dll**                       Third-party library files
       **bin/win64_v142/experimental_usd_writer/usd/**                         Third-party runtime resources
       **bin/win64_v142/experimental_usd_writer/Third-Party_Licenses/**        Third-party license files
      ======================================================================= ========================================================= 

      The USD writer libraries must be located under **//bin/win64_v142/experimental_usd_writer**.  
      This folder should reside alongside your HOOPS Exchange binaries, including *A3DLIBS.dll*.

      .. image:: usd_bin_folder_win.png


   .. tab:: GNU Linux (GCC)

      ======================================================================= ========================================================= 
       Folder/File     Description                                              
      ======================================================================= ========================================================= 
       readme_experimental_USDwriter.txt                                       How-to file
       **bin/linux64/experimental_usd_writer/**                                Binaries folder
       bin/linux64/experimental_usd_writer/libexperimental_wusd.so             Main library file
       **bin/linux64/experimental_usd_writer/\*.so**                           Third-party library files
       **bin/linux64/experimental_usd_writer/usd/**                            Third-party runtime resources
       **bin/linux64/experimental_usd_writer/Third-Party_Licenses/**           Third-party license files
      ======================================================================= ========================================================= 

      The library files should be placed under **//bin/linux64/experimental_usd_writer**.  
      This folder must exist within your HOOPS Exchange installation alongside *libA3DLIBS.so*.

      .. image:: usd_bin_folder_lin.png

Dependencies
------------

Legal information regarding third-party libraries is available in the  
*bin/linux64/experimental_usd_writer/Third-Party_Licenses/* directory.
