ExchangeSharp

C# language binding for HOOPS Exchange.

It can be built and used on the following platforms:

• Windows
• Ubuntu Linux
• macOS

A video introducing ExchangeSharp can be found here:

Expectations and Disclaimer

This is an unsupported implementation. It is being developed as experimental code.

Don't read any further unless you are willing to work with the developers to identify issues that will arise.

If you are coming to this page with an expectation that you will obtain a complete and entirely tested C# wrapper, STOP! This is not the project for you.

Expect that you may need to modify delegate declarations in order to make some functionality accessible.

Expect an API that is very similar to the HOOPS Exchange native C API.

If you are going to use ExchangeSharp, you will need a basic understanding of the HOOPS Exchange C API.

HOOPS Exchange 2023 SP2 U1 now has official support for C#. Therefore, this repo will no longer receive regularly updates.

Description

This is a direct C# language binding for HOOPS Exchange implemented in the namespace TS3D.Exchange.Direct.

Functionality found in A3DSDKDraw.h is not included.

ExchangeSharp was created using libclang to parse the Exchange headers. By traversing the declarations, we have reasonable certainty for complete coverage.

What do you mean by "Direct"?

ExchangeSharp utilitizes the P/Invoke approach for providing a cross-platform binding for the C# language. It does this by declaring all of the data types used by the native Exchange library in a compatible C# form.

"Direct" implies that the C# syntax you will use to access Exchange will closely resemble its C counterpart. Functions are looked up in the Exchange library and directly invoked.

ExchangeSharp is automatically generated by a libclang-based tool. As such, all source files (except Library.cs) should be considered disposable.

Disadvantages.

I put this first because I don't think you'd read it if it came afer the advantages.

1. The generation algorithm isn't perfect (yet?). This means that some function signatures (see API.cs) may be incorrect.
   1. This means you will have to make minor modifications to this file if you find an issue.
   2. Unless you want to make this modification every time you update the ExchangeSharp code base, you should provide the change so we can improve the generation algorithm.
2. Memory management within the Exchange data model must still be understood.
   1. The lifetime of C# objects in the Direct interface has no bearing on the underlying Exchange data model.
   2. You use ExchangeSharp functions to create objects, and you must use functions to explicitly delete them.
3. You must understand what an IntPtr is and how to use it.
   1. Exchange uses a lot of opaque pointers as "handles" into the Exchange data model. This is still the case even when using ExchangeSharp.

Advantages

This approach has several advantages.

1. Memory: Data is not copied. It is directly mapped using struct objects. (See Structs.cs)
2. Speed: There is no "middle" code. When you call an Exchange function using C#, you are directly invoking the code and nothing between. (See API.cs)
3. Stability: Since it is based on the Exchange C API there will seldom be major changes to the interface.
4. Familiar: The code you write will look familiar:

A3DAsmModelFileData d;
API.Initialize( out d );
if( A3DStatus.A3D_SUCCESS == API.A3DAsmModelFileGet( model_file, ref d ) ) {
    // Use object here

    // Free the object-
    API.A3DAsmModelFileGet( IntPtr.Zero, ref d );
}

Confidence

API	Description	Confidence
Libraray.cs	Hand-written library management code	98%
Structs.cs	Declarations of all struct data types	99%
Enums.cs	Declarations of all enum data types	99%
Contants.cs	Declarations of all #define constancts	98%
API.Initialize	C# Implementation of A3D_INITIALIZE_DATA	90%
API.A3D*Get	Get functions for structs	99%
API.A3D*Create	Create functions for structs	99%
API.A3D*Edit	Edit functions for structs	80%
API.cs (other)	Other Exchange functions	80%

Prerequisites

In order to build and use ExchangeSharp, the following software components are required:

• HOOPS Exchange (or binary compatible version)

  • Be sure you have Exchange installed and licensed correctly.
  • Unpack the archive.
  • Place hoops_license.h and hoops_license.cs in the include folder.
  • Build and run the sample applications contained within.

• .NET Core 3.1

Building ExchangeSharp.dll

1. Clone the ExchangeSharp repository.
   • git clone https://github.com/techsoft3d/ExchangeSharp.git
2. Build ExchangeSharp
   • dotnet build <version>
3. ExchangeSharp.dll can be found in the <version>/src/bin/Debug/netcoreapp3.1 folder.

Building and Running the Examples

The examples folder contains projects that illustrate basic use of ExchangeSharp. To build each project:

1. Copy hoops_license.cs to the example's folder you want to build.
2. Change your current working directory to the example's folder.
3. Use the command dotnet build to build
4. Run using dotnet run. Most examples take the command line argument --exchange <exchange_bin_dir>.
   1. Alternatively you can edit update your environment variable to include the Exchange bin folder for your platform (PATH, LD_LIBRARY_PATH, DYLD_LIBRARY_PATH).

What is Classes.cs?

Similar to the ExchangeToolkit, ExchangeSharp includes classes with the postfix "Wrapper". These classes call API.Initialize and Get in the constructor, and they free upon destruction. Using these classes results in code that looks like this:

var d = new A3DAsmModelFileWrapper( model_file );
// Use object here
for( int idx = 0; idx < d.m_uiPOccurrencesSize; ++idx ) {
    var po = Marshal.ReadIntPtr(d.m_ppPOccurrences, idx * Marshal.SizeOf( typeof(IntPtr) ) );
    var po_d = new A3DAsmProductOccurrenceWrapper( po );
    // use Product Occurrence data...
}

Structs that do not have corresponding Get function (A3DVector3dData for example) are wrapped as well. Code provided in the examples folder make use of these wrapper classes in order to make the implementation more concise.