The Conventions of HOOPS in Java
Linking with the HOOPS Java Bindings
If you are only using 3dgs, this is what you must do to set it up:
- 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.
- 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:
- 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.
- 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:
import com.techsoft.hoops.*;
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:
static
{
System.loadLibrary("hjmvo<version>_vc80");
}
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:
Define_Callback_Name
Define_Exit_Handler
UnDefine_Exit_Handler
Define_Callback_Name
UnDefine_Callback_Name
Show_Callback_Name
Set_Driver
QSet_Driver
However, there may be a few functions available that are not properly wrapped or
working, such as Define_Error_Handler.
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*:
char ex[1024];
HC_Show_Alias("?picture", ex);
printf("?picture=%s\n",ex);
is replaced in Java by StringBuffer:
StringBuffer ex = new StringBuffer ("");
HJ.Show_Alias("?picture", ex);
System.out.println("?picture="+ex);
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]:
float x,y,z;
HC_QShow_Camera_Position("?picture", &x, &y, &z);
printf(" x=%f y=%f z=%f\n", x, y, z);
is replaced in Java by single element float arrays:
float[] x = new float[1];
float[] y = new float[1];
float[] z = new float[1];
HJ.QShow_Camera_Position("?picture", x, y, z);
System.out.println("x=" + x[0] + "y=" + y[0] + "z=" + z[0]);
Arrays can be used in Java in a similar manner as they are used in C. Thus,
the C HOOPS code:
float v1[3] = {1.0f,0.0f,0.0f};
float v2[3] = {0.0f,1.0f,0.0f};
float v3[3];
HC_Compute_Cross_Product(v1,v2,v3);
printf("%f %f %f\n", v3[0], v3[1], v3[2]);
is replaced in Java by:
float[] v1 = {1.0f,0.0f,0.0f};
float[] v2 = {0.0f,1.0f,0.0f};
float[] v3 = new float[3];
HJ.Compute_Cross_Product(v1,v2,v3);
System.out.println( v3[0]+" "+v3[1]+" "+ v3[2]);
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