==========================
HOOPS for C/C++ Developers
==========================

C/C++ Defines
=============

To have access to function prototypes for the ``HC_`` routines that comprise the HOOPS Visualize API, users of HOOPS Visualize include the file *hc.h* in their programs. Users of HOOPS I.M. additionally include *hic.h* to have access to the intermediate mode routines. The intermediate mode routines are NOT a layer on top of Visualize. The intermediate mode routines directly access the data and procedures used by HOOPS Visualize itself. Inclusion of *hic.h* automatically includes hoops.h for the user. The conventions and coding style for Visualize itself are embodied in *hoops.h*. This coding style is easily identifiable by viewing driver source code. The following words are defined in *hoops.h*:

* null
* countof
* true, false
* forever
* until
* global, globaldata
* local
* nobreak
* stack

Don't use these words in HOOPS I.M. programs.


Routine Names: Prefixes
=======================

Each routine name, such as ``Insert_Polyline``, in your Visualize 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 and C++, users must preface the routines with **HC_** as in ``Reset_System``.
        
		
Common Names
============

All HOOPS Visualize 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 returns a reference to the element. 
* **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.
* **UnSet**: Undoes a Set. (Allows an attribute value to be inherited once again from a higher level.)
* **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.


Data Type Names and Language Declarations in C/C++
==================================================

HC Conventions
---------------

The datatypes used by the ``HC_`` subroutines  translate as follows:

.. raw:: html::

	<table class="table_style1">
	<tr> 
	  <th>HOOPS</th>
	  <th>HOOPS (HC) type</th>
	</tr>
	<tr> 
	  <td>'HC_KEY'</td>
	  <td> HC_KEY</td>
	</tr>
	<tr> 
	  <td> 'integer'</td>
	  <td> int</td>
	</tr>
	<tr> 
	  <td>'boolean'</td>
	  <td>int</td>
	</tr>
	<tr> 
	  <td>'short'</td>
	  <td>short</td>
	</tr>
	<tr> 
	  <td> 'float'</td>
	  <td>float</td>
	</tr>
	<tr> 
	  <td>'string'</td>
	  <td>char * (zero terminated)</td>
	</tr>
	<tr> 
	  <td>'single point'</td>
	  <td>struct {float x,y,z;} or float [3]</td>
	</tr>
	<tr> 
	  <td>'point vector'</td>
	  <td>struct {float x,y,z;} [n] or float [n][3]</td>
	</tr>
	<tr> 
	  <td>'array of 4 floats'</td>
	  <td>float [4]</td>
	</tr>
	<tr> 
	  <td>'4 x 4 array of floats'</td>
	  <td> float [4][4]</td>
	</tr>
	<TR> 
	  <TD>'vector of short integers' </td>
	  <TD>short [n]</td>
	<TR> 
	  <TD>'vector of long integers'</td> 
	  <TD>long [n]</td> 
	<TR> 
	  <TD>'2-D array of short integers'</td> 
	  <TD>short [r][c]</td> 
	<tr> 
	  <td>'vector of integers'</td>
	  <td>int [n]</td></td>
	</tr>
	</table>


Because the bit pattern used by HOOPS might not be identical to the bit pattern of your ``TRUE`` macro, avoid an explicit comparison of a Boolean to "TRUE". Instead, rely on the C property of "not equal to zero". If the routine definition specifies *Passed by reference*, your argument in C must be either a simple variable preceded by an "&" or a pointer value. If the routine definition specifies a *returns* clause, you can ignore the return value in C. This might not be true in other languages. If an actual parameter which is a string is specified as *Passed by reference. Returned to user*, you must provide the address of a simple variable large enough to hold what might be returned. (A call to ``Define_System_Options`` can be used to specify the maximum C string length that HOOPS should return.)


HIC Conventions
---------------

The additional data types used by the ``HIC_`` subroutines translate as follows:


HIC_Marker, HIC_Point, HIC_Polygon, HIC_Polyline, and HIC_Text
..............................................................

Structures containing the defining information and some derived information for a 3D geometry primitive (as inserted by an application into the database). The defining vertices of these primitives are given with respect to object coordinates. You can create new instances of these structures with the ``HIC_New_(geometry)`` functions. You can determine the defining parameters (e.g., vertex count and vertex arrays) of given instances with the ``HIC_Show_...`` functions. 


HIC_Geometry
............

A union type incorporating all the HOOPS geometry types. including ``HIC_Marker``, ``HIC_Point``, ``HIC_Polygon``, ``HIC_Polyline``, ``HIC_Text``, and the other geometry types not directly relevant to the HOOPS I.M. programmer.


HIC_Segment_Info
................

A complex structure containing information describing a particular segment. It is passed as an argument to a small set of segment-dependent methods. There is not much you can do with it but pass it on to the segment-dependent ``HIC_...`` functions that you might call. 


HIC_Window_Info
...............

A complex type describing a window. In intermediate mode, it occurs only as an argument to the "select windows"; callback. 


HIC_Rendition
.............

A large structure type containing a complete set of values of all HOOPS attributes. Every method for which there is a callback point takes a rendition as one of its arguments, the net rendition  nr, giving all the attribute values in effect at that callback point. Most of the ``HIC_...`` functions take a rendition argument. You can query the current values of attributes in a rendition by calling the ``HIC_Show_..._(attribute)`` functions. You can create new renditions with ``HIC_New_Rendition``, and you can set attribute values in a new rendition with the ``HIC_Set_(attribute)`` functions. 


HIC_Text_Info
.............

A complex type that contains information about a particular text string at an intermediate stage in the rendering pipeline. You can query the relevant parameters of an instance of this type with the  HIC_Show_Text_(parameters) functions. Example::

	typedef struct point {float x,y,z; } HIC_Point; 
	typedef struct dc_point {float x,y,z;} HIC_DC_Point;
	typedef struct vector {float x,y,z;} HIC_Vector;

While these three types have the same declaration, they are used to distinguish device 
coordinates from object coordinates and points from vectors. 


Rectangle Types
...............

Example::

	typedef struct int_rectangle { 
	   int left, right, bottom, top; 
	} HIC_Int_Rectangle;

	typedef struct clip_rectangle {
		struct clip_rectangle *next; 
		int left, right, bottom, top;
	} HIC_Clip_Rectangle;

The linking pointer next in ``HIC_Clip_Rectangle`` is for internal use, and of no concern to the I.M. programmer.


Color Types
...........

Example::

	typedef struct HIC_rgb {
	  float red, green, blue; 
	} HIC_RGB;
	 
	typedef struct HIC_rgba {
		float red, green, blue, alpha;
	} HIC_RGBA; 

These are most commonly used for specifying a color as three/four floats for the RGB/RGBA components. In the ``HIC_RGB`` and ``HIC_RGBA`` types, the components are generally all between 0 and 1.  

Internally, HOOPS also uses a four-byte color type, ``HIC_RGBAS32``. The ordering of the components as defined by ``PREFERRED_RGB32`` however, depends on the CPU, specifically on its byte-ordering convention or its endian-ness::

	typedef union HIC_rgbas32 {
		HIC_Integer32 whole_thing;
		struct {
			/*
			 The ordering of HIC_RGB for 32 bits is system dependent. We define
			 the HIC_RGB ordering correctly here and in phedron.h for local display 
			 or display on same-vendor hardware. If the display is across the
			 network to different-vendor hardware, then the Drivers must check
			 the ordering of HIC_RGB and rearrange it if necessary.
			*/
		
			unsigned char PREFERRED_RGB32;
		} rgb;
	} HIC_RGBAS32;

Thus, when dealing with a color variable ``color`` of this type, you can refer to all four components as ``color.whole_thing``. You also can safely reference, say, the red component as ``color.rgb.r``. But, if you want your code to be platform-independent, then you cannot make assumptions as to which physical byte this represents.


Stand-Alone Example Programs in C
=================================

Stand-alone HOOPS Visualize programs are located in the *<VISUALIZE>/demo/common/standard* directory and in the *<VISUALIZE>/demo/common/tutorial* directory. The C programs demonstrate usage of most HOOPS/3dGS routines and are useful in understanding the basic syntax of the API as well as for test purposes. Executables can be built with the supplied makefile.
