The Conventions of HOOPS in Java


Linking with the HOOPS Java Bindings

Java Defines

Routine Names

HOOPS Routines Available in Java

Differences Between Using HOOPS with Java and with C

Datatypes Names and Language Declarations

Stand-Alone Example Programs


Linking with the HOOPS Java Bindings

If you are only using 3dgs, this is what you must do to set it up:
  1. Put HJ.jar in your classpath. This can either be done via the command line for both compiling and running, or it can be set in the manifest file for your project.
  2. Ensure that HJ.jar, hj<version>_vc80.dll, and hoops<version>_vc80.dll are in your application's directory.
If you are planning to use MVO, there are several additional things you must do:
  1. Put HJMVO.jar in your classpath (along with HJ.jar). This can either be done via the command line for both compiling and running, or it can be set in the manifest file for your project.
  2. Ensure that HJMVO.jar, hjmvo<version>_vc80.dll, and hoopsmvo<version>_vc80.dll are in your application's directory.
In addition to the files mentioned above, you may need to include jawt.dll, java_awt_canvas.dll, and hoops_stream<version>_vc80.dll in your directory.
The files referred to above are located in the [installation]/bin directory.


Java Defines

To have access to function prototypes for the routines that comprise the HOOPS API, Java users must use the following line:
If you are only using 3dgs, this is all the setup you should have to do. Afterwards, you should be able to call all of the 3dgs functions via the HJ class.
However, if you intend to use MVO, you will also need to add this block of code into your main application class:

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 Java, all calls to the HOOPS/3dGS API are made through the HJ class, such as:

StringBuffer ex = new StringBuffer ("");
HJ.Show_Alias("?picture", ex);

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 Java

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

Differences Between Using HOOPS with Java and C

Pointers and write-back values

The largest difference between using HOOPS with Java 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. Because Java does not have pointers, we have to use other means of passing in by reference.
For example, the C HOOPS code that uses a char*:
is replaced in Java by StringBuffer:
NOTE: You must always pass a new or empty StringBuffer, as HJ uses append internally to return the string.
The C HOOPS code that uses &[float_value]:
is replaced in Java by single element float arrays:
Arrays can be used in Java in a similar manner as they are used in C. Thus, the C HOOPS code:
is replaced in Java by:
Be sure to allocate enough room in the array, lest HOOPS writes into unallocated memory and causes a segfault.

HOOPS Keys

In Java, all HOOPS keys are treated as integers.
Return to Top

Datatype Names and Language Declarations in Java

The Java datatypes translate as follows:
 
HOOPS HOOPS (HC) type Java type
'string' HC type String
'writes string' const char * StringBuffer
'HC_KEY' HC_KEY int
'int' int int
'writes int' &int int[1]
'float' float float
'writes float' &float float[1]
'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 Java

Several simple HOOPS Java program are located in subdirectories under the [installation]/demo/java directory. The programs demonstrates the usage of a select number HOOPS routines as called from the Java Native Interface and is useful in understanding the basic syntax of the API as well as for test purposes.

In the java_simple directory, there is also a more complex demo application that mimics the HOOPS MFC Simple application. This is a good place to see how the setup is done to set up HOOPS MVO with Java, and proper placement of various calls.

The java_simple_3dgs_only contains some very simple applications that only use 3dgs, and draws into a user-created window.

The java_standard contains some legacy Java demo applications, that draw into a HOOPS standalone window.

The java_awt_canvas directory does not actually contain a demo application; it contains a project that implements the basic HCanvas class that is used for drawing to a window. This project should be prebuilt, so you should not have to do anything with it.
Return to Top