The following lists routines and options that have become obsolete during the course of development of HOOPS. These routines will be maintained permanently for the benefit of existing programs, but it is recommended you use the newer replacement routines when writing new programs.

Here is a full list of the obsolete HOOPS routines:

Here is a full list of the obsolete options by routine name:


Obsolete Routines


Compute_Minimized_Shell

PURPOSE

Removes redundant vertices and degenerate faces from data that can be used to describe a shell.

CALLING SEQUENCE

Compute_Minimized_Shell (pcount, points, flist_length, face_list, options,
new_pcount, new_points, new_flist_length, new_face_list, point_mapping_list, face_mapping_list)

------------------------------------------------------------------------------------
pcount                integer        Number of valid points in points.                  
points                point vector   Vector of x-y-z triplets for the coordinates of    
                                     the vertices that could be used to build the       
                                     shell. (A simple N ¥ 3 array can also be used.     
                                     Fortran callers should reverse the sub             
                                     scripts.) Passed by reference always.              
flist_length          integer        Total number of integers in face_list.             
face_list             vector of      Encoded description of how to connect the          
                      integers       points to build the faces of the shell. Passed     
                                     by reference always.                               
options               string         A quoted string or a string variable con           
                                     taining a list of desired options. Passed by       
                                     reference always.                                  
new_pcount            integer        Number of valid points in new_points after         
                                     computation. Returned to caller. Passed by         
                                     reference always.                                  
new_points            point vector   Vector of x-y-z triplets for the coordinates of    
                                     the non-redundant vertices that could be           
                                     used to build the shell. (A simple N ¥ 3 array     
                                     can also be used. Fortran callers should           
                                     reverse the subscripts.) Returned to caller.       
                                     Passed by reference always.                        
new_flist_length      integer        Total number of integers in computed               
                                     new_face_list. Returned to caller. Passed by       
                                     reference always.                                  
new_face_list         vector of      Encoded description of how to connect the          
                      integers       points to build the faces of the computed          
                                     shell. Returned to caller. Passed by reference     
                                     always.                                            
point_mapping_list    vector of      Mapping of vertices from the original point list   
                      integers       to the vertices in the new (computed) point        
                                     list. Eliminated points are mapped to -1.          
                                     Returned to caller. Passed by reference always.    
face_mapping_list     vector of      Mapping of faces from the original face list       
                      integers       to the new (computed) face list. Eliminated        
                                     faces are mapped to -1. Returned to caller.        
                                     Passed by reference always.                        
------------------------------------------------------------------------------------

DETAILS

The HOOPS routine Insert_Shell accepts a set of points, an encoded description of how to connect the points to form the faces of a shell. Insert_Shell performs no interrogation of the data received. It has no provision for eliminating redundant points nor for ignoring disconnected points. Compute_Minimized_Shell accepts data normally used to insert a shell and returns a new set of data with redundancies and discontinuities removed. This new data can then be used to insert a shell. The arrays point_mapping_list and face_mapping_list are available to help you refer to the new data, if given indices to the original data.

Programs designed to work with geometric modelers often receive geometry in a stream. This means they cannot ascertain the overall connectedness of a shell's faces. For instance, to define a diagonally-split quadrilateral using two faces, one needs only four vertices, with two of them referenced twice. While it is geometrically correct to redefine the "re-used" vertices, for a total of six, face-connectivity information is lost. This is because duplicated points, though equivalent, are still distinct---each face has its "own" vertices. Compute_Minimized_Shell recaptures the connectivity by eliminating the duplicated vertices and forcing faces to share the remaining unique vertices.

Faces that refer to fewer than three unique vertices are eliminated.

Since shells are arbitrary collections of faces, Compute_Minimized_Shell can be used to convert a group of polygons into a coherent shell. The advantage is less data must be sent to HOOPS. Performance is improved since fewer points must be transformed and clipped.

Compute_Minimized_Shell does not allocate memory for you. All arrays passed to it must contain adequate storage.

The following choices are recognized for options:

[no] orphan elimination

If this option is set, points that are not referenced by any face are removed. The default is "orphan elimination".

[no] tolerance [= nnn oru / nnn % fru]

"Tolerance" controls the identification of duplicate points. If a specification is given in object-relative units (oru), then the points that are separated by a distance less than this value are considered equal.

Often, one cannot ascertain a "good" value for an object-relative tolerance. In this case, specify the tolerance using "feature-relative units (fru)". Feature size is defined to be the smallest non-zero distance between any two adjacent vertices on any face. It is calculated internally by Compute_Minimized_Shell, and is constant for the entire collection of faces. The feature-relative tolerance is expressed as a percentage of this minimum distance. A setting less than "tolerance = 100% fru" guarantees that unequal vertices on a single face won't be eliminated.

"No tolerance" is the same as "tolerance = 0 oru".

The default is "no tolerance".

NOTES

If you are not interested in the mapping lists, pass a null pointer for either the point_mapping_list or the face_mapping_list.

SEE ALSO

Insert_Shell, Show_Shell, Show_Shell_Size.

This function has been replaced by Compute_Optimized_Shell. The new function can take an additional optional argment for normal information, renamed so that this version could stay behind for backward compatibility.

Back


Define_Color

PURPOSE

Identical to Define_Color_Name---adds a new color to the already existing colors in the system's tables.

CALLING SEQUENCE

Define_Color (name, er-name, ish-name, definition)

-----------------------------------------------------------------------------
name          string   Simple name to be added to the list of definitions.       
er-name       string   The "er" (1st degree) combining form of the simple name   
                       above.                                                    
ish-name      string   The "ish" (2nd degree) combining form.                    
definition    string   The actual color, in terms of colors that already exist.  
-----------------------------------------------------------------------------

VARIANTS

UnDefine_Color (name)

----------------------------------------------------------------
name    string   Name to be removed from the list of legal colors.  
----------------------------------------------------------------

DETAILS

These routines have been replaced by the identical routines Define_Color_Name and UnDefine_Color_Name---the naming was changed because of a conflict among the corresponding "Show" routine names.

Back


Edit_Pixel_Array

PURPOSE

Modifies one, some, or all of the pixel values in a previously-inserted Pixel Array.

CALLING SEQUENCE

Edit_Pixel_Array (key, xoffset, yoffset, xcount, ycount, pixels)

--------------------------------------------------------------------------------------
key         HC_KEY       The numeric identifier returned by a previous call to            
                         KInsert_Pixel_Array or KInsert_Pixel_Array_By_Ref.               
xoffset,    integer      Offset, in pixels, from the upper-left corner of the original    
yoffset                  pixel array at which to begin editing. The upper-left-most       
                         original pixel is numbered (0, 0); values increase going right   
                         and going down.                                                  
xcount,     integer      The number of columns and the number of rows of pixels to        
ycount                   be changed, going down and to the right. The counts,             
                         together with the offsets, represent a rectangular change        
                         region within the original pixel array.                          
pixels      2-D array    The pixel values to be used. The numbers represent indices       
            of short     into the current Color Map. The first value in pixels is the     
            integers     upper-left -most of the change region; the next value is just    
                         to its right, etc. Passed by reference always.                   
--------------------------------------------------------------------------------------

DETAILS

Edit_Pixel_Array lets you make minor changes to a large pixel array as it sits in the database. You don't have to delete or flush the segment and reinsert it from scratch.

Edit_Pixel_Array operates on a rectangular subregion of the original pixel array, and replaces all the pixel values in that region with new ones. If the original pixel array was specified "by reference"---and the system did not copy it---the Edit will modify the actual original user memory locations.

It is not possible to change the size of a pixel array except by starting over.

This routine has been replaced by Edit_Image.

Back


Flush_Segment

PURPOSE

Empties all the drawing primitives out of a segment.

CALLING SEQUENCE

Flush_Segment (segment)

-------------------------------------------------------------------
segment    string   Segment(s) to be Flushed. May contain wildcards.   
-------------------------------------------------------------------

DETAILS

Note: This routine has been replaced by Flush_Geometry, which has the same meaning and takes the same arguments as Flush_Contents. See Flush_Contents for details.

The geometrical contents of the specified segment(s), consisting of Inserted items and Include specifications, are removed. The attribute settings and the subsegments, if any, remain unchanged and the segment still exists under the same name. The contents of the subsegments, if any, are not affected. Flush_Segment is often used when some picture information comes and goes and is different each time, but the structure of the segment tree must remain the same.

NOTES

A Clear_Display routine has been provided too---it happens to be nearly synonymous with Flush_Segment. Clear_Display exists because when you're running in "non-segmented" mode, and there isn't a "segment" to be seen anywhere, it wouldn't be appropriate to be talking about flushing a segment. Clear_Display operates on "?Picture".

Back


Insert_Pixel_Array

PURPOSE

Inserts image data---a rectangular array of pixel values---into your scene.

CALLING SEQUENCE

Insert_Pixel_Array (x, y, z, width, height, pixels)

------------------------------------------------------------------------------------
x, y, z    float        The coordinates of the center of the pixel array.               
width,     integer      The number of columns and the number of rows of pixels          
height                  in this pixel array. Must be positive.                          
pixels     2-D array    The pixel values to be used. The numbers represent              
           of short     indices into the current Color Map. The first value in          
           integers     pixels is the upper-left-most of the pixel array; the next      
                        value is just to its right; the value at ( width +1) in the     
                        array is the first pixel on the second row from the top, etc.   
                        Passed by reference always.                                     
------------------------------------------------------------------------------------

VARIANTS

KInsert_Pixel_Array (x, y, z, width, height, pixels), returns key

QInsert_Pixel_Array (segment, x, y, z, width, height, pixels)

QKInsert_Pixel_Array (segment, x, y, z, width, height, pixels), returns key

Insert_Pixel_Array_By_Ref (x, y, z, width, height, pixels)

KInsert_Pixel_Array_By_Ref (x, y, z, width, height, pixels), returns key

QInsert_Pixel_Array_By_Ref (segment, x, y, z, width, height, pixels)

QKInsert_Pixel_Array_By_Ref (segment, x, y, z, width, height, pixels), returns key

--------------------------------------------------------------------------------------
key        HC_KEY           Unique numeric identifier for this particular pixel array.    
                            Returned to caller.                                           
x, y, z    float            As above.                                                     
width,     integer          As above.                                                     
height                                                                                    
pixels     2-D array of     As above.                                                     
           short integers                                                                 
segment    string           Segment(s) to be inserted into, if other than the currently-  
                            open segment.                                                 
--------------------------------------------------------------------------------------

DETAILS

Pixel Arrays are intended for the display of raster images. They are unique in that they are laid out in terms of screen space: once the center has been located (transformed from object space) everything else is defined solely in terms of the pixels on the screen of your current display device. Thus, pixel arrays are extremely display-dependent and will look different on different devices depending on their resolutions, aspect ratios, and, indeed, whether or not they actually display in terms of pixels.

The pixel values defined here are not full-fledged HOOPS color triplets or strings; they are just look-up indices. The actual colors are defined indirectly by the current "Color Map" attribute. Please note you must define an appropriate color map to match your pixel array. Also note that the color look-up is performed at Update time, not just at declaration time---changes to the color map will be reflected in the appearance of pixel arrays that already exist.

The _By_Ref ("by reference") routines differ from the regular routines only in that the system is allowed not to make a copy of your data (at the system's option) but instead will remember where your pixel array was located. Then, whenever the pixels need to be redisplayed the array originally passed in pixels is used, not an internal copy. This can speed up the call to Insert_Pixel_Array and it can save memory. But be careful---when you insert "by reference" you are guaranteeing that pixels is going to remain valid and that you're not going to touch it (except via Edit_Pixel_Array) until such time as the whole Pixel Array database entry finally gets deleted. Also note that, as mentioned, the system can make a copy anyhow if it needs to, so you shouldn't assume that Edits will be readable back in the original array.

If you have a choice (if it is possible to define the picture so) it is much better to use line, polygons, etc., rather than Pixel Arrays since that way 1) your picture's appearance will be independent of the display device, and 2) you will have many more ways to manipulate it. Pixel Arrays are appropriate when that's the format of the data arriving from the outside world, or if you are drawing photograph-like images.

NOTES

If a Pixel Array is not completely contained within the current Window, it will be clipped appropriately.

You may find it convenient to set up a camera volume that matches the number of pixels on your screen. This will simplify meshing adjacent pixel arrays exactly.

If there is an error the KInsert routine will return a -1.

This routine has been replaced by the more powerful Insert_Image routine.

Back


Mark_As_Updated

PURPOSE

This function tells HOOPS to ignore any changes made to part of the segment tree since the segment was last updated.

CALLING SEQUENCE

Mark_As_Updated (segment)

Mark_As_Refresh_Needed (segment, left, right, bottom, top)

-------------------------------------------------------------------------------------
segment         string   The segment pathname of a branch of the HOOPS tree that         
                         has changes that needed to be flagged. (All sub-segments        
                         of the specified segment are included in the specification)     
                         Wildcards are legal.                                            
left, right,    float    The extent of the region to be redrawn. It defines a clipping   
bottom, top              rectangle in "local window" coordinates (the window in          
                         which the "segment" appears). The repaint that occurs as a      
                         result of this call will be clipped to the box. Normally you    
                         would use "?Picture" and (-1,1,-1,1) to force a full screen     
                         redraw.                                                         
-------------------------------------------------------------------------------------

DETAILS

Normally when you make a change to the HOOPS tree (by deleting geometry, moving objects, etc.) HOOPS marks the modified segments as requiring a redraw. At the next Update_Display or equivalent call, HOOPS traverses the list of segments requiring redraws, and either overlays the changes on top of the existing scene (Incremental Updates), or erases and redraws the windows in which changes were made (in cases where incremental updates are not legal). The end result is that after the Update_Display call, the picture on the screen matches the picture described by the HOOPS tree. "Update Interrupts" allow an update to be interrupted and later modified (for example, the user could change the camera angle half way through an update); but eventually HOOPS will start redrawing the scene again until it arrives at a correct picture matching the most recent database.

Sometimes you may not want the screen to exactly match the HOOPS tree in order to reduce screen redrawing. For instance, when performing a complex hidden surfaced drawing the user may want to abort the update altogether (leading to an incorrect, half drawn picture). The user may want to work with the half-drawn image, and then later force a full update.

Mark_As_Updated marks the named segment as having been already updated, so that when the segment tree is traversed, the picture will not be redrawn. If changes are made after this call, or if the parent segment is changed, this call might have no effect at the time of traversal. This call is normally executed from a window segment.

Mark_As_Refresh_Needed is the complement function of Mark_As_Updated. This function tells HOOPS to mark part of the segment tree as changed and hence requires a repaint. The next Update_Display will redraw any of the flagged segments, with the changes clipped to a specified box. A possible use for this call would be repairing of a partially obscured window.

This function has been superceded by Control_Update.

NOTE

When using Mark_As_Updated and Mark_As_Refresh_Needed, the application is taking major responsibility for the resulting picture, and how it is drawn. Use of these functions can easily lead to convoluted code that is hard to understand or maintain. These functions should be used sparingly, or not at all.

Back


Move_Pixel_Array

PURPOSE

Changes the location, in object space, of a previously-inserted Pixel Array.

CALLING SEQUENCE

Move_Pixel_Array (key, x, y, z)

-----------------------------------------------------------------------
key        HC_KEY  The numeric identifier returned by a previous call to   
                   KInsert_Pixel_Array or KInsert_Pixel_Array_By_Ref.      
x, y, z    float   The new coordinates for the center of the pixel array.  
-----------------------------------------------------------------------

DETAILS

Simply allows you to override the original specifications and move a pixel array to a new location. The new location is specified as an absolute location, rather than as a relative distance from the old location.

This routine has been replaced by Move_Image.

Back


Request_Location

PURPOSE

Retrieves one screen position from the locater device (mouse, tablet, trackball, etc.)

CALLING SEQUENCE

Request_Location (x, y)

---------------------------------------------------------------------
x, y    float   The location, in terms of the outermost screen window.   
                The values are always returned in the range -1 to +1.    
                Passed by reference. Returned to user.                   
---------------------------------------------------------------------

DETAILS

If the database has been changed since the last Update, a new Update is performed automatically. The locater device attached to the "?Picture" segment is then polled until a button is pressed, or, if a button is already pressed, until the screen position changes.

The position is then adjusted to be in terms of the outermost HOOPS window, the button status is saved, and finally the position is returned to the original caller. The status can be retrieved by calling Show_Location_Status.

In pseudo-C, Request_Location corresponds to

		if (first_time) {
			Enable_Location_Events ("?locater",  "?Picture", "v*^")
			first_time = false 
				} 
		Get_Location (&x, &y) 

The "x" and "y" are then returned to the original caller. The purpose of the Enable_Location_Events is to keep the locater running smoothly even when the program is calling Update_Display explicitly.

NOTE

This routine has been replaced with Get_Location.

Back


Set_Text_Size

PURPOSE

Allows you to scale your text up and down.

CALLING SEQUENCE

Set_Text_Size (size)

-------------------------------------------------------------------------
size    float   Scale factor. 0.5 makes the letters half as big; 2.0 makes   
                them twice as big.                                           
-------------------------------------------------------------------------

VARIANTS

QSet_Text_Size (segment, size)

UnSet_Text_Size ()

QUnSet_Text_Size (segment)

Show_Text_Size (retsize)

QShow_Text_Size (segment, retsize)

Show_Net_Text_Size (retsize)

QShow_Net_Text_Size (segment, retsize)

--------------------------------------------------------------------------
segment    string   Name of the segment(s) to be changed or shown.            
size       float    As above.                                                 
retsize    float    The size previously stored in the database. Returned to   
                    caller. Passed by reference in all languages.             
--------------------------------------------------------------------------

DETAILS

All text strings within the scope of the Text Size are scaled as specified. Text alignment, spacing, etc., are computed with respect to the new size.

Text Size as a separate attribute is now obsolete: the function has been turned into the "size" option of the Text Font attribute. Set_Text_Size will still work; it just turns around and calls Set_Text_Font. Show_Text_Size will also still work, but only if the size was specified in "subscreen relative" units, either indirectly by Set_Text_Size or directly by Set_Text_Font. UnSet_Text_Size now removes the "size" option from the Text Font attribute.

To convert Text Size calls to Text Font calls, multiply size by 0.03 and specify "subscreen relative" units to Set_Text_Font.

For example,

			Set_Text_Size (2.0) 

becomes

			Set_Text_Font ("size=0.06 sru") 

Back


Set_User_Value

PURPOSE

Allows you to save one number of your own choosing in the segment structure.

CALLING SEQUENCE

Set_User_Value (data)

-----------------------------------------------------------------------
data    HC_POINTER_SIZED_INT Any long integer, or any other value    
                             which fits in a long integer.                                                    
-----------------------------------------------------------------------

VARIANTS

Set_User_Option_By_Index (data)

UnSet_User_Option_By_Index (data)

QSet_User_Option_By_Index (segment, data)

QUnSet_User_Option_By_Index (segment, data)

QSet_User_Value (segment, data)

UnSet_User_Value ()

QUnSet_User_Value (segment)

Show_User_Value (rdata)

QShow_User_Value (segment, rdata)

Show_Net_User_Value (rdata)

QShow_Net_User_Value (segment, rdata)

PShow_Net_User_Value (count, keys, rdata)

--------------------------------------------------------------------------
segment    string   Name of the segment(s) to be modified.                    
data       long     As above.                                                 
rdata      long     The stored value, returned to user. Passed by reference   
                    always.        
count      integer  The number of keys in the keys array    
keys     vector of  The list of keys starting with the owning segment and following
     HC_KEY's       all the way back to the root segment or other desired segment.
                                               
--------------------------------------------------------------------------

DETAILS

Allows you to save one arbitrary piece of information into a segment. After hit-testing, for example, the name or key of the `hit' segment might not be sufficient for your program to figure out what's going on or what the segment represents. You could save a bit of information (or a pointer into your own database), which would simplify operations, and use Show_User_Value to make the necessary conversion from segment name to saved database pointer.

User Values have been replaced, in most situations, by renumbered keys and by User Options.

NOTES

On most machines, a long integer is big enough to hold a pointer to an arbitrary data structure. You should cast the pointer in the call, and cast the return value of Show_User_Value back again. If you want to be completely portable, though, you should just use the integer as an index into a look-up table, which then points to the structure.

If the "User Value" value of a segment does point to a structure, and the segment is deleted, the structure will still be there---the application program must be completely in charge of keeping track of it.

"User Options" are very similar to "User Value"; the difference is that the stored value is one or more labelled text strings rather than a single integer. If you want to store a whole collection of data, your program can save time by using User Value to hold a binary pointer to a data structure. If you want to be more structured and more portable, though, use User Options.

"Renumbered" keys are also very similar to "User Value". Renumbered keys must be non-negative; user values can be anything.

Back


Show_Location_Status

PURPOSE

Retrieves the state of the various buttons on the locater device.

CALLING SEQUENCE

Show_Location_Status (status)

------------------------------------------------------------------------------
status    integer   Bit-mask representing the buttons that were pressed at the    
                    time of the most recent Request_Location. The first           
                    button will cause the first bit to be on, the second button   
                    the second bit, etc. Passed by reference. Returned to user.   
------------------------------------------------------------------------------

DETAILS

The Request_Location routine polls the hardware locater device (a mouse or a tablet, for example), looks for at least one button to be pressed, and returns the (x, y) locater position. Some locater devices have more than one button though, and it's possible to have your program take different actions depending on which button caused Request_Location to return. Show_Location_Status returns this button information to you.

In pseudo-C, Show_Location_Status corresponds to

	Show_Location_Source (&locater, &picture, &action, &status) 

The "status" is then returned to the original caller, and the other information is discarded.

NOTE

If you depend on the existence of more than one button, it means you're depending on having a particular kind of hardware locater device. This might not be wise.

This routine has been replaced with Show_Location_Source and Show_Selection_Source.

Back


Show_Net_Color_By_Index/Value

PURPOSE

None.

CALLING SEQUENCE

Show_Net_Color_By_Index (types, index)

Show_Net_Color_By_Value (types, color_space, a, b, c)

QShow_Net_Color_By_Index (segment, types, index)

QShow_Net_Color_By_Value (segment, color_space, a, b, c)

------------------------------------------------------------------------------------
segment       string      Name of the segment to be shown.                              
other         (various)   The stored attribute values. All values returned to caller.   
parameters                Passed by reference in all languages.                         
------------------------------------------------------------------------------------

DETAILS

These routines were inserted by mistake. A "net" color would virtually always be composed of several different color values, but these routines don't allow several color values to be returned at once. So they are unfortunately not useful.

Please see Show_One_Net_Color instead.

Back


Show_NURBS_Curve_Count

CALLING SEQUENCE

Show_NURBS_Curve_Count(key, degree, cp_count, knot_count)

------------------------------------------------------------------------------------------
key             HC_KEY         As above
degree          integer        As above
cp_count        integer        As above
knot_count      integer        Number of knots in the NURBS curve.  Returned to
                               caller.  Passed by reference always.
------------------------------------------------------------------------------------------

DETAILS

HC_Show_NURBS_Curve_Count was replaced by HC_Show_NURBS_Curve_Size. This function is identical to the new function in every way, except for the absence of a new parameter, weight_count.

Use Show_NURBS_Curve_Count to determine how large the control_points, and knots arrays are going to be, before you actually call Show_NURBS_Curve.

SEE ALSO

Edit_NURBS_Curve, Show_Selection_Element, KInsert_NURBS_Curve, Get_Selection, Begin_Contents_Search, Compute_Coordinates, D(Command).

Back


Show_Pixel_Array

PURPOSE

Returns the rectangular array of pixels, as referenced by a key.

CALLING SEQUENCE

Show_Pixel_Array (key, x, y, z, width, height, pixels)

----------------------------------------------------------------------------------
key        HC_KEY       Unique numeric identifier pointing to a pixel array in the    
                        database.                                                     
x, y, z    float        The coordinates of the center of the pixel array. Returned    
                        to caller. Passed by reference always.                        
width,     integer      The number of columns and the number of rows in the           
height                  pixel array. Returned to caller. Passed by reference always.  
pixels     2-D array    The pixel values currently stored in the pixel array refer    
           of short     enced by key. Returned to caller. Passed by reference         
           integers     always.                                                       
----------------------------------------------------------------------------------

VARIANTS

Show_Pixel_Array_Size (key, x, y, z, width, height)

Show_Partial_Pixel_Array (key, xpos, ypos, xlen, ylen, pixels)

---------------------------------------------------------------------------------------
key           HC_KEY       As above.                                                       
x, y, z       float        As above.                                                       
width,        integer      As above.                                                       
height                                                                                     
xpos, ypos    integer      Offset, in pixels, from the upper-left corner of the original   
                           pixel array, at which to return data. The upper-left-most       
                           original pixel is numbered (0, 0); values increase going        
                           right and going down.                                           
xlen, ylen    integer      The count of columns and rows of pixels to be returned,         
                           going to the right and up. The counts, together with the        
                           offsets, represent a rectangular region within the original     
                           pixel array.                                                    
pixels        2-D array    As above.                                                       
              of short                                                                     
              integers                                                                     
---------------------------------------------------------------------------------------

DETAILS

Show_Pixel_Array reads back the pixel values currently stored in a pixel array. This is especially useful if the pixel array was edited several times using Edit_Pixel_Array and you need to determine the final result. The key for the pixel array might come from Show_Selection_Element or Find_Contents, or it might have been saved by your program when the pixel array was created.

Use Show_Pixel_Array_Size to determine how large the pixels array is going to need to be, before you actually call Show_Pixel_Array.

Use Show_Partial_Pixel_Array to return the values of the pixels in just a portion of the pixel array at a time. This is helpful if the pixel array is very large and your program cannot or need not store the entire array at once. The rectangular region defined by the parameters to this function must be within the bounds of the pixel array.

This routine has been replaced by Show_Image.

Back


Show_Selection_Item

PURPOSE

Returns the key of the database item that was selected by the user, plus an offset within that item.

CALLING SEQUENCE

Show_Selection_Item (key, offset1, offset2)

------------------------------------------------------------------------------
key         HC_KEY    The key of the "best match" element of your scene. Passed   
                      by reference always. Returned to user.                      
offset1,    integer   A rough indication of what came closest within the          
offset2               element pointed to by key. Passed by reference always.      
                      Returned to user.                                           
------------------------------------------------------------------------------

DETAILS

This routine has been replaced by Show_Selection_Element, which is identical except that an offset3 parameter has been added to support shells and meshes.

Show_Selection_Item works by calling Show_Selection_Element and then discarding the third offset.

Back


Show_Selection_Location

PURPOSE

Shows the location that has just been used to select something. The location is returned in terms of both window coordinates and world coordinates.

CALLING SEQUENCE

Show_Selection_Location (xw, yw, xc, yc, zc)

-------------------------------------------------------------------------------
xw, yw        float   The screen location in terms of the innermost and front      
                      most containing window. Values are in the range of -1 to 1   
                      within that window. Passed by reference always. Returned     
                      to user.                                                     
xc, yc, zc    float   The screen location in terms of the view of the world seen   
                      by the camera. Please see below for details. Passed by ref   
                      erence always. Returned to user.                             
-------------------------------------------------------------------------------

DETAILS

Once a "selection" event has reached the front of the event queue and become the current event, your program can ask for details about it. One of the details available is the exact screen location that the user was pointing at.

Show_Selection_Location returns this location in two different forms. The window coordinates are in terms of the immediate containing HOOPS window---if the user were pointing at the upper-left-corner of a window on the screen, for example, xw would be -1 and yw would be +1.

The "camera-relative" coordinates are given in terms of what that screen location means with respect to your virtual camera's view of the system's world coordinates. This coordinate system is the one you're using when you specify and insert 3-D lines, polygons, and so forth into your scene. It's the coordinate system of the scene itself.

The conversion from screen coordinates to world coordinates is made by assuming the Camera Position corresponds to your viewing position, and the Camera Target corresponds to the center front of the physical screen window. The actual screen positions then defines a "line of sight" passing through your 3-D scene.

If a piece of geometry was selected (see Show_Selection_Element), (xc, yc, zc) represents the point at which this virtual line of sight passes closest to or through the selected geometry, in world coordinates. If only a window was selected, then (xc, yc, zc) is the point where the line of sight intersects the "camera reference plane"---i.e., the plane that contains the current Camera Target and is perpendicular to the camera axis.

NOTES

The camera used for computations is that in effect for the segment named by Show_Selection and Show_Selection_Pathname.

A "line of sight" vector can be defined by (xc, yc, zc) minus the Camera Position.

You can gain whole-screen coordinates, if you've been using subwindows, by calling QShow_Net_Window on the segment named by Show_Selection_Pathname, and then converting the local window coordinates.

If you've been using modelling matrices, you can gain "object space" coordinates by calling QShow_Net_Modelling_Matrix on the segment named by Show_Selection_Pathname, and then converting the world coordinates.

Show_Selection_Location is not identical to Show_Location. Show Location goes with "location" events, not selection events, and location events differ in that they represent the locater device's "raw" coordinates, and have no knowledge of segments, cameras, windows, or even display screens.

Back


Update_Driver_Data

PURPOSE

Used to provide special circumstance features to overcome obstacles created by the Windows programming environment.

CALLING SEQUENCE

Update_Driver_Data (segment, directive)

--------------------------------------------------------------------------------
segment     string   The name of the driver segment. Passed by reference.           
directive   string   The type of action that the routine is to take. Passed by ref  
                     erence.                                                        
--------------------------------------------------------------------------------

DETAILS

This routine is currently only useful on Microsoft Windows. It is documented here for completeness. This routine is used in consultation with HOOPS Technical Support to:

  • Output HOOPS pictures to hardcopy printers that require banding of the output.

  • Force a refresh of the Windows colormap.

    There are currently two valid choices for directive.

    band output

    When this directive is supplied, the segment argument is ignored. HOOPS updates the data for all of its active drivers. This is done to facilitate an application's banding of its printer output.

    reset palette

    When this directive is supplied, HOOPS uses the driver segment identified by the segment argument and reloads the color palette to match the colors for that segment. This function is most useful when working with the Galaxy window manager and HOOPS.

    NOTES

    This routine has been not yet been replaced. It is anticipated that banding of printer output will be supported in a more natural fashion in a future release of HOOPS. Improved color handling is already slated as a feature for a future HOOPS release.



    Obsolete Options


    Insert_Text_With_Encoding

      HOOPS/3dGS implemented unicode support in version 6.0. This encoding method is recognized worldwide and has become the standard for international application development. As such, the standard options for text encoding in HOOPS have become obsolete, including:
      1. ISO Latin

        The entire ISO (International Standards Organization) Latin character set, encoded as a mixture of 8-bit and 16-bit characters. Text is expected to be an array of bytes. Walking through the array, if a byte has the value of 1 through 31 then a 16-bit value is assumed and another byte must follow. The first byte becomes the high-order part of the character number and the second byte is the low-order part. If a byte has the value 32 or more, it is taken as the low-order part of the number and the high-order part is taken as zero. A high byte of zero corresponds to the ISO "Latin 1" character set. In C the byte string is terminated with the usual C null byte. In Fortran, assembling "ISO Latin" strings would require heavy use of the "char" function.

        In summary, the four characters 65-66-256-515 might be written in C as "AB\1\0\2\3," although stylistically it might be safer to say "AB\001\000\002\003." Note the embedded null byte.

        In Fortran, the same example would be

        'AB'//char(1)//char(0)//char(2)//char(3).

      2. JEC

        See Insert_Text in the HOOPS Kanji chapter.

      3. EUC

        See Insert_Text in the HOOPS Kanji chapter.

      4. 16

        Straight ("raw") 16-bit encoding. Every 16-bit character is encoded as two bytes in the input text, high-order byte first. In C the string must be terminated with a double null; character zero cannot be represented. A "specific" font must be chosen for display (see Set_Text_Font); the characters will be passed straight to the display driver.

        Encoded characters will often be conveniently handled as arrays of 16-bit integers, rather than in the above packed-byte format. Compute_Text_From_Text16 and Compute_Text16_From_Text can be used to make the necessary conversion.

    Set_Driver_Options

        Set_Driver_Options ("debug = NO_WINDOWS_HOOK")

        The driver debug bit, NO_WINDOWS_HOOK, is now officially obsolete. The new way of accomplishing that is the following:

        HC_Set_Driver_Options( "disable input = all")

        NO_WINDOWS_HOOK will continue to work as always, but should not be used for any new code.