The Conventions of HOOPS in C#


Linking with the HOOPS C# Bindings

C# Defines

Routine Names

HOOPS Routines Available in C#

Differences Between Using HOOPS with C# and with C

Datatypes Names and Language Declarations

Stand-Alone Example Programs


Linking with the HOOPS C# Bindings

Applications must reference the HOOPS C# objects:

hoops<version>_cs80.dll (for 3DGS)

hoops_mvo<version>_cs80.dll (optional - for MVO functionality)
located in the [installation]/bin directory.


C# Defines

To have access to function prototypes for the routines that comprise the HOOPS API, C# simply have to add a reference to the objects listed in the previous section.
Once the reference has been added, you can access all of the relevant classes.
IMPORTANT: You should also add this "define" to your document somewhere:

#if _M_X64
using HLONG = System.Int64;
#else
using HLONG = System.Int32;
#endif
Then, for 64 bit projects, you should define the _M_X64 (you can name this anything you want). You should use "HLONG" in all places where you would normally use a C "long". This is because C#'s "long" is always 64 bit, whereas C's "long" is often 32 bit, and are incompatible. Using HLONG will help ensure compatability. (You can also simply use ints for 32 bit projects and longs for 64 bit projects, but things may get confusing).


Routine Names

Prefixes

Each routine name, such as Insert_Polyline, in your HOOPS program must have a prefix before the name will actually be usable on your computer system. The prefix varies depending on which language you're calling from, and sometimes depending on the brand of the language you're calling from. When calling from C#, all calls to the HOOPS/3dGS API are made through the HCS class, such as:

HCS.Open_Segment("newsegment");
HCS.Insert_Line(0,0,0, 1,1,1);
HCS.Close_Segment();
The MVO classes can be used in pretty much the same way as the C/C++ variants.

Common Names

All HOOPS routine names follow a standard pattern: the first part of the name is an active verb indicating what's to be done, and the second part is a descriptive noun.
The most common verbs are
Define Changes a global system status, or adds something to a system-wide table.
Insert Incorporates a new picture element into the current segment and into the scene.
KInsert Incorporates a new picture element and returns a reference key to the element.
QInsert Quickly opens a different segment.  Inserts a new picture element and closes the segment
DInsert Double precision version of insert.  Pass doubles instead of floats.
Edit Changes the definition of an existing picture element.
DEdit Double precision version of edit.  Pass doubles instead of floats.
Set Loads an explicit new value for an attribute.
QSet Quickly opens a different segment. Sets and closes the segment.
UnSet Undoes a Set. (Allows an attribute value to be inherited once again from a higher level.)
QUnSet Quickly opens a different segment. UnSets and closes the segment.
Show Retrieves an item of information from the system.
DShow Double precision version of show.  Returns doubles instead of floats.
Begin Initializes a database information search.
Find Steps an information search along.
End Completes an information search.
(Please note that there are a number of miscellaneous verbs that arise from the various state-modifying routines, such as Dolly_Camera and Rename_Segment. These less frequently occurring verbs are usually self explanatory.)
The most common nouns include the following:
Segment The routine works with a graphics segment (a place for storing picture elements) as one element.
Camera The routine positions or moves the viewing camera.
Object The routine works with the "real" objects (as organized into segments) from which your scene is composed.
Text The routine affects the text labels appearing in the scene.
Return to Top

HOOPS Routines Available in C#

Most functions available under C are available in C# except for:
Return to Top

Differences Between Using HOOPS with C# and C

Functions

Two functions are different under C# than C:
Both take an HCSU.errfunc object (which is a delegate) as their argument. If null is passed to UnDefine_Error_Handler, it will remove the default HOOPS error handler. If an already registered HCSU.errfunc is passed, that handler will be removed.
Here is an example of declaring an error handler:

public void error_handler(int category, int specific, int severity, int msgc, sbyte ** msgv, int stackc, sbyte ** stackv)
{
}

public void init(){
HCS.Open_Segment("?picture");
HCSU.errfunc error_hndlr_ptr = new HCSU.errfunc(error_handler);
HCS.Define_Error_Handler(error_hndlr_ptr);
HCS.Close_Segment();
}
Note: You may have to set your project to "allow unsafe code" in order to use the error handler, as it uses pointers.

Pointers and write-back values

The largest difference between using HOOPS with C# and C is found when you have a write-back value, i.e. you pass a pointer to a function and it writes a value or values to that location. In HOOPS C#, arrays can typically be written to without any extra help, while single variables need a "ref" keyword before the object name (similar to the "&" in C/C++).
For example, the C HOOPS code that uses a char*:
is replaced in C# by StringBuilder:
NOTE: The "StringBuilder" type is used for write-back values. You should use the "string" type for constant string values. These are enforced by the function signatures, so you should not be able to pass in the wrong type.
The C HOOPS code that uses &[float_value]:
is used in a similar manner in C#, with the "ref" keyword:
Arrays can be used in C# in a similar manner as they are used in C. Thus, the C HOOPS code:
is accomplished in C# by:

HOOPS Keys

Another difference between using HOOPS with C# and C is found when dealing with HOOPS keys. In C#, you should use HLONG (assuming you defined it as mentioned here: C# Defines) for the keys. Thus, the C code:
is replaced in C# by:
Return to Top

Datatype Names and Language Declarations in C#

The C# datatypes translate as follows:
 
HOOPS HOOPS (HC) type C# type
'string' HC type string
'writes string' const char * StringBuilder
'HC_KEY' HC_KEY HLONG (System.Int32 / System.Int64)
'int' int int
'writes int' &int ref int
'float' float float
'writes float' &float ref float
'point' float[3] float[3]
'writes point' &float float[]
'writes bytes' unsigned char * sbyte[]
'writes ints' &int int[]

 
Return to Top

Stand-Alone Example Programs in C#

Two simple, stand-alone HOOPS C# programs are located in the [installation]/demo/csharp/ directory. These program demonstrates the usage of a select number HOOPS routines as called from the C# Native Interface and is useful in understanding the basic syntax of the API as well as for test purposes.
The project in the chsarp_simple directory is an MVO based application. This project contains most of the functionality of "mfc_simple" application.
The project in the chsarp_simple_3dgs_only directory only uses 3DGS. This project is extremely basic, and implements only a few basic HOOPS calls. It contains use of the error handler, so you may use it as a reference.

Return to Top