|
SilverScreen API Library Reference |
Run-Time Routines by Category
Data Conversion Functions
| Name | Description |
| format_double | Format double value to text string |
| text_to_color | Convert text string to color number |
| text_to_rgb | Convert text string to RGB value |
| text_to_xyz | Convert text string to XYZ value |
| xyz_to_text | Convert XYZ value to text string |
| Name | Description |
| chdir | Change current working directory |
| get_drive | Get current MS-DOS drive |
| getcwd | Retrieve current working directory |
| mkdir | Make directory |
| rmdir | Delete directory |
| set_drive | Set current MS-DOS drive |
File Handling Functions
| Name | Description |
| access | Check for file or directory existence |
| file_date | Retrieve date of file on disk |
| file_time | Retrieve time of file on disk |
| find_first | Check for file existence |
| find_next | Check for file existence |
| remove | Delete disk file |
| rename | Rename disk file |
| unlink | Delete disk file |
Graphics Functions
| Name | Description |
| draw_line | Draw line in pixel coordinates |
| draw_point | Draw point in pixel coordinates |
| draw_world_line | Draw line in world coordinates |
| draw_world_point | Draw point in world coordinates |
| pixel_clear | Clear area specified in pixel coordinates |
| read_pixel | Read pixel value |
| record_visibility | Record entity visibility state |
| refresh_lines | Redraw saved lines |
| reset_visibility | Restore saved entity visibility state |
| screen_discard | Remove top saved screen from stack |
| screen_pop | Retrieve top saved screen from stack |
| screen_push | Push saved screen onto stack |
| screen_restore | Display top saved screen on stack |
| screen_save | Save screen area onto stack |
| LINE_STYLE | Macro definition |
| LINE_WIDTH | Macro definition |
| MAKE_WIDTH_STYLE | Macro definition |
| Name | Description |
| color_to_rgb | Retrieves red, green and blue components of color number |
| rgb_to_color | Converts red, green blue components to color number |
| BLUE_COLOR | Blue component of RGB |
| GREEN_COLOR | Green component of RGB |
| RED_COLOR | Red component of RGB |
| MAKE_RGB | Make RGB from color number, and red, green, blue components |
| THE_COLOR | Retrieve color number from RGB |
Screen Text Functions
| Name | Description |
| clear_area | Clear character area on screen |
| cls | Clear screen |
| locate | Locate cursor |
| text_mode_begin | Begin text mode |
| text_mode_cursor | Set text mode cursor mode |
| text_mode_end | End text mode |
| text_mode_locate | Locate text mode cursor |
| wchar | Write character on graphics screen |
| wcolor | Write text string on graphics screen, color specified |
| wcolorc | Write text string on graphics screen, color specified, then clear to end of line |
| wstring | Write text string on graphics screen, color not specified |
| wstringc | Write text string on graphics screen, color not specified, then clear to end of line |
Mathematical Functions
| Name | Description |
| equal_double | Test for floating point equality, within epsilon |
| dsin | sin function with degrees as argument |
| dcos | cos function with degrees as argument |
| dtan | tan function with degrees as argument |
| zero_double | Test for floating point equality to zero, within epsilon |
Process and Environment Control Functions
| Name | Description |
| abort | Terminate program execution |
| chain | Chain to .EX file, no return |
| chain_and_return | Chain to .EX file, with return |
| get_env | Retrieve environment string value |
| system2 | Invoke MS-DOS command interpreter, no screen save, text mode |
| system3 | Invoke MS-DOS command interpreter, no screen save, no text mode |
Direct Structure Access Functions
| Name | Description |
| bos_extents | Calculate extents of BOS |
| bos_on_screen | Calculate intersection of BOS extents with screen |
| color_of_edge | Return color number of object edge |
| get_bos | Return direct pointer to SilverScreen BOS |
| get_endpoints | Retrieve endpoints (XYZs) of primitive |
| get_prim | Return direct pointer to SilverScreen primitive |
| interference | Determine interference between two BOSes |
| make_path | Copy path of direct pointer to BOS into character buffer |
| primitive_plane | Retrieve plane equation of primitive |
| primitive_plane2 | Retrieve plane equation of primitive |
| rgb_of_edge | Return RGB of object edge |
| vertex1_of_edge | Return first vertex number of object edge |
| vertex2_of_edge | Return second vertex number of object edge |
| xyz_of_vertex | Return address of XYZ of vertex |
| xyz1_of_edge | Return address of first XYZ of object edge |
| xyz2_of_edge | Return address of second XYZ of object edge |
Structure Loading Access Functions
| Name | Description |
| load_ss_attribute | Retrieve value of BOS attribute |
| load_ss_variable | Load value of SilverScreen variable |
Control Variable Access Functions
| Name | Description |
| cv_get | Retrieve control variable value |
| cv_set | Set control variable value |
Panel Input Functions
| Name | Description |
| attach_box_item | Add box prompting item |
| box_prompt | Allow selection of an item from a list |
| box_prompt_multiple | Allow selection of multiple items from a list |
| panel_empty | Display empty panel |
| panel_icon | Prompt using panel icons |
| panel_icon2 | Prompt using panel icons, with mask setting |
| panel_input | Prompt for text string using a panel |
| panel_message | Display a message in a panel |
| pm_box | Add a menu selection to the current panel |
| pm_box2 | Add a menu selection to the current panel |
| pm_color | Add a color prompt to the current panel |
| pm_comment | Add a comment field to the current panel |
| pm_displacement | Add a displacement prompt to the current panel |
| pm_distance | Add a distance prompt to the current panel |
| pm_double | Add a prompt for a double value to the current panel |
| pm_execute | Display current panel and accept user input |
| pm_font | Add a prompt for a TrueType or SilverScreen font to the current panel |
| pm_formatted | Add a prompt for a formatted double value to the current panel |
| pm_generic | Add a generic item prompt to the current panel |
| pm_help_file | Associate the contents of a text help file with the current panel |
| pm_help_line | Associate a line of a help text with the current panel |
| pm_icon | Add an icon prompt to the current panel |
| pm_icon2 | Add an icon prompt to the current panel, with masking |
| pm_initialize | Initialize current panel |
| pm_integer | Add a prompt for an integer value to the current panel |
| pm_line_width | Add a prompt for an line width to the current panel |
| pm_menu | Add a menu prompt to the current panel |
| pm_rgb | Add a prompt for an RGB value to the current panel |
| pm_text | Add a prompt for a text string to the current panel |
| pm_xyz | Add a prompt for an XYZ value to the current panel |
| Name | Description |
| display_icon | Display an icon in the menu area |
| icon | Prompt using icons in menu area |
| icon2 | Prompt using icons in menu area, with masking |
| Name | Description |
| bt_close | Close b-tree data and index files |
| bt_create_data | Create empty b-tree data file |
| bt_create_tree | Create empty b-tree index file |
| bt_delete | Delete record/index entry pair from b-tree database |
| bt_erase | Remove record from b-tree database |
| bt_find | Search b-tree database for key value |
| bt_find2 | Search b-tree database for key/record number values |
| bt_flush | Flush all b-tree databases to disk |
| bt_insert | Insert a new entry into a b-tree database |
| bt_next | Move to next index entry in a b-tree database |
| bt_open | Open a b-tree index and data file pair |
| bt_previous | Move to previous index entry in a b-tree database |
| bt_read | Retrieve the data from a record in a b-tree database |
| bt_set_first | Set the read marker to start of a b-tree index file |
| bt_set_key | Set the read marker to location in a b-tree index file associated with a key value |
| bt_set_last | Set the read marker to end of a b-tree index file |
| bt_store | Create a new record in a b-tree database file |
| bt_update | Update a b-tree index entry with a new record number |
| bt_write | Write a new record to a b-tree database at record number |
Simple Prompting Functions
| Name | Description |
| ask_multiple | Prompt for response according to button items |
| ask_yn | Prompt for yes/no response |
| fence_pgroup | Prompt for primitive group using fence |
| fence_qgroup | Prompt for BOS group using fence |
| pick_entity | Prompt user for BOS using pick mode |
| pick_primitive | Prompt user for primitive using pick mode |
| prompt_color | Prompt for a color number |
| prompt_displacement | Prompt for a displacement value |
| prompt_distance | Prompt for a distance value |
| prompt_entity | Prompt for BOS using either scan mode or pick mode |
| prompt_line_width | Prompt for a line width |
| prompt_pgroup | Prompt for primitive group using scan mode or pick mode |
| prompt_point | Prompt for XYZ value, set worldx, worldy and worldz |
| prompt_primitive | Prompt for primitive using either scan mode or pick mode |
| prompt_qgroup | Prompt for BOS group using scan mode or pick mode |
| prompt_rgb | Prompt for an RGB value |
| scan_entity | Prompt user for BOS using scan mode |
| scan_primitive | Prompt user for primitive using scan mode |
Printing Functions
| Name | Description |
| printer_close | Close printer port |
| printer_open | Open printer port |
| printer_send | Send data to printer port |
Transformation Matrix Functions
| Name | Description |
| tm_clear | Initialize transformation matrix to unity |
| tm_copy | Copy transformation matrix |
| tm_cspace | Retrieve c-space values into transformation matrix |
| tm_espace | Retrieve e-space values into transformation matrix |
| tm_extents | Compute extents of BOS or primitive relative to transformation matrix |
| tm_inverse | Compute transformation matrix inverse |
| tm_multiply | Multiply transformation matrices |
| tm_rotate_x | Generate x-axis rotation matrix |
| tm_rotate_y | Generate y-axis rotation matrix |
| tm_rotate_z | Generate z-axis rotation matrix |
| tm_scale_x | Generate x-axis scaling matrix |
| tm_scale_y | Generate y-axis scaling matrix |
| tm_scale_z | Generate z-axis scaling matrix |
| tm_to_2d | Create transformation matrix by moving two line segments to xy-plane |
| tm_to_plus_x | Create transformation matrix by moving line segment to x-axis |
| tm_to_plus_z | Create transformation matrix by moving line segment to z-axis |
| tm_transform | Transform point to another coordinate system using a transformation matrix |
| tm_transform_bos | Transform BOS to another coordinate system using a transformation matrix |
| tm_translate | Generate translation matrix based on XYZ |
| Name | Description |
| c_to_w | Convert a point from c-space to w-space |
| cross_product | Compute cross-product of three points |
| dot_product | Compute dot-product of two points |
| get_plane | Compute the plane formed by three points |
| intersect | Compute the intersection point between two line segments |
| intersect_3_plane | Compute the intersection point between three planes |
| intersect_line_plane | Compute the intersection point between a line and a plane |
| p_to_w | Compute world point from screen coordinates |
| point_on_line | Test whether a point lies on a line segment |
| point_on_plane | Test whether a point is on a plane |
| point_on_round | Test whether a point lies on an arc or circle |
| point_vs_plane | Compare a point against a plane |
| point_vs_polygon | Compare a point against a polygon |
| point_vs_solid | Compare a point against a solid |
| rel_distance | Compute relative distance between two points |
| w_to_c | Convert a point from w-space to c-space |
| w_to_p | Compute screen coordinates from a world point |
| xyz_add | Add two XYZ's |
| xyz_angle | Compute the angle between three XYZ's |
| xyz_clear | Set XYZ components to zero |
| xyz_distance | Compute distance between two XYZ's |
| xyz_div | Divide an XYZ by a double value |
| xyz_equal | Test whether two XYZ's are equal, within epsilon |
| xyz_mult | Multiply an XYZ by a double value |
| xyz_round | Round XYZ components to zero, based on epsilon |
| xyz_sub | Subtract two XYZ's |
| xyz_zero | Test whether XYZ components are zero, using epsilon |
SilverScreen Drawing Hierarchy
| Name | Description |
| is_entity | Test for existence of BOS name |
| make_path | Copy BOS name into buffer |
| paint_entity | Draw BOS with a color |
| paint_primitive | Draw primitive with a color |
| congruent | Test whether two solids are identical |
| extents | Retrieve BOS or primitive extents |
| get_tag | Retrieve tag value |
| fetch_tag | Search drawing for BOS and tag name |
SilverScreen Interface and Environment Functions
| Name | Description |
| clear_away_lines | Blank out text lines on the screen |
| clear_icons | Clear icon (menu) area |
| clear_window | Clear current window to its background setting |
| count_windows | Count the number of windows in the current screen |
| delta_worldx | Move the world cursor in an x direction |
| delta_worldy | Move the world cursor in a y direction |
| delta_worldz | Move the world cursor in a z direction |
| error_message | Display an error message and wait for a keystroke |
| error_text | Copy SilverScreen error text into a buffer |
| eval_expression | Evaluate SilverScreen expression |
| get_cspace | Retrieve current c-space settings |
| get_direct_pointer | Return a direct pointer to a system structure |
| get_group | Retrieve a group name |
| get_group_item | Retrieve an item name from a named group or the q-group |
| get_pgroup_item | Retrieve an item name from the q-group |
| get_version | Retrieve SilverScreen version information |
| get_view | Retrieve current view parameters |
| jump_menu | Invoke jump menu |
| mark_area | Mark an area in the current screen |
| path_drawing | Copy drawing directory name into a buffer |
| path_execution | Copy execution directory name into a buffer |
| path_home | Copy home directory name into a buffer |
| path_library | Copy library directory name into a buffer |
| path_silver | Copy SilverScreen directory name into a buffer |
| path_temp | Copy temporary directory name into a buffer |
| quick_menu | Invoke quick menu |
| ss_command | Execute a system command |
| sys_ablock | Copy the path of the current annotation block into a buffer |
| sys_block | Copy the path of the current block into a buffer |
| sys_drawing | Copy the name of the current drawing into a buffer |
| sys_drawing_fullname | Copy the full name, including path, of the current drawing into a buffer |
| sys_object | Copy the path of the current object into a buffer |
| sys_screen | Copy the name of the current screen into a buffer |
| sys_title | Copy the title of the current drawing into a buffer |
| sys_window | Return the current window number |
| view_file | Display a text file in a scrollable window |
Generic Data Functions
| Name | Description |
| collect_generic | Assemble a list of SilverScreen generic items |
| get_generic | Return item from generic item list |
| prompt_generic | Prompt for a generic item |
Custom Menu Support
| Name | Description |
| menu | Load a custom menu and allow user selection (one-shot only) |
| menu_check_item | Place a checkmark by a menu item |
| menu_enable_item | Enable/disable/gray a menu item |
| menu_persist | Load a custom menu and allow user selection (menu remains in place) |
| menu_unload | Unload a custom menu previously loaded by menu |
Keyboard Input and Mouse Cursor Control
| Name | Description |
| inchar | Return next keyboard or mouse event, remove from input queue |
| nextkey | Return next keyboard or mouse event, do not remove from queue |
| pointer_char_locate | Locate mouse arrow, in character coordinates |
| pointer_char_position | Return mouse character coordinates |
| pointer_locate | Locate mouse arrow, in pixel coordinates |
| pointer_mode | Set current pointer input mode |
| pointer_position | Return mouse pixel coordinates |
System Variable Support
| Name | Description |
| sysvar_text | Retrieve value of system text variable |
| sysvar_value | Retrieve value of system variable |
| sysvar_xyz | Retrieve value of system XYZ variable |
| Name | Description |
| assert | Test program assertion |
| language_now | Retrieve current language name |
| tfile_close | Close current tfile |
| tfile_gets | Retrieve text string associated with message number from current tfile |
| tfile_make | Build a tfile for message text |
| tfile_open | Open current tfile |
| translate_keyword | Translate a keyword to or from English |
| Stacktrace | Display local variables of currently active functions |
Run-Time Routines
access
int access ( char *filename, int mode )
char *filename; // pathname of file or directory
int mode; // permission mode
| Synopsis | #include
"silver.h" The access function determines if path exists and can be accessed in access mode mode. |
||||||||||
| Parameters | filename is a
null-terminated string specifying the name of the file or path. mode is a number
specifying the access mode. The permissible values for mode are given by the following
table:
|
||||||||||
| Return Value | If path refers to a file, then access returns 0 if the file exists and can be accessed in mode. If path refers to a directory, access returns 0 if the directory exists. If path does not exist or is cannot be accessed by the specified mode, then access returns -1. | ||||||||||
| See Also | chdir, rmdir, rename, unlink |
application_name
void application_name ( char
*name )
char *name; // new application name
| Synopsis | #include
"silver.h" Sets or resets the application name that appears in the upper left corner the SilverScreen window. |
| Parameters | name is a null-terminated string. If the string is not empty, name will be used to establish a new application name. If name is an empty string, then the application name will be reset to the default SilverScreen application name. |
ask_multiple
int ask_multiple ( char
*button_names, char *message )
char *button_names; // button text
char *message; // prompting message
| Synopsis | #include
"silver.h" The ask_multiple function displays a multi-line message in a panel, and waits for a response from the user. ask_multiple may be used for more complicated prompting than ask_yn. |
| Parameters | button_names and message are both null-terminated strings. The button_names parameter is broken up into space-delimited strings, which are used as text on corresponding buttons in a popup (thus implicitly specifying the number of buttons). The message parameter is used as prompting; for any embedded vertical bar characters ('|') in message, the prompt is broken at that point, the '|' character is discarded, and the text following the '|' is placed on the subsequent line at the left edge of the prompt area. |
| Return Value | The index number of the selected button (1 to <number of buttons>) is returned if a selection was made, and 0 is returned otherwise (by hitting Escape). |
| See Also | ask_yn |
ask_yn
int ask_yn ( char *message )
char *message; // multi-line message
| Synopsis | #include
"silver.h" The ask_yn function displays a multi-line message in a panel and waits for a response from the user. |
| Parameters | message is a null-terminated string, used as prompting; for any embedded vertical bar characters ('|') in message, the prompt is broken at that point, the '|' character is discarded, and the text following the '|' is placed on the subsequent line at the left edge of the prompt area. |
| Return Value | If the user responds affirmatively, then the function returns 1; if they reply negatively or presses ESCAPE, then 0 is returned. |
| See Also | ask_multiple |
| Example | if (ask_yn("Save
modified drawing?")) ... if
(ask_yn("All files will be deleted.|Proceed?")) |
assert
void assert( int expression )
int expression; // the assertion
| Synopsis | #include
"assert.h" The assert macro evaluates the assertion denoted by expression and if it is zero (or false), and the special "no debug" identifier NDEBUG is not defined, causes an error message (which includes the name of the file, source line number, and text of the assertion) to be displayed on the screen, and then calls the abort function. Otherwise, no action is taken. |
| Parameters | expression is an integral expression, that should normally be non-zero; that is, in the normal course of program execution, the programmer would expect that the value of the expression is non-zero, and if it is zero, then this is a program logic error. |
| Comments | assert is implemented as a macro. |
| See Also | abort |
attach_box_item
void attach_box_item (
char *item )
char *item; // text to attach to box prompt list
| Synopsis | #include
"silver.h" The attach_box_item function attaches item to an internally maintained list of items for a future call to box_prompt or box_prompt_multiple. |
| Parameters | item is a null-terminated string |
| See Also | box_prompt, box_prompt_multiple |
bos_extents
int bos_extents (
BOS_NODE *bos, SS_XYZ *high, SS_XYZ *low )
BOS_NODE *bos; // pointer to block, object or symbol
SS_XYZ *high; // upper limits of 3D extents
SS_XYZ *low; // lower limits of 3D extents
| Synopsis | #include
"ssnodes.h" The bos_extents function returns the 3D extents of the indicated entity. |
| Parameters | bos is a pointer to a SilverScreen entity, as obtainable by a call to get_bos. high and low are pointers to SS_XYZ structures that are to receive the upper and lower extents, respectively. |
| Return Value | bos_extents returns 1 if bos is a valid pointer to a SilverScreen BOS; otherwise 0 is returned. |
| See Also | extents, get_bos |
bos_on_screen
int bos_on_screen (
BOS_NODE *bos )
BOS_NODE *bos; // pointer to block, object or symbol
| Synopsis | #include
"ssnodes.h" The bos_on_screen function determines whether the indicated entity is visible and its extents overlap the boundary defined by the current window. |
| Parameters | bos is a pointer to a SilverScreen entity, as obtainable by a call to get_bos. |
| Return Value | bos_on_screen returns 1 if bos is visible and its extents overlap the current window, and 0 otherwise. |
| Comments | A return value of 1 does not guarantee that bos is in the window (it may be concave); however, a return value of 0 does guarantee that no portion of bos may be seen in the window. |
| See Also | get_bos |
box_prompt
int box_prompt ( char
*message, char *buf, int sort_flag )
char *message; // box_prompt messages
char *buf; // buffer to receive selection
int sort_flag; // enables/disables item sorting
| Synopsis | #include
"silver.h" The box_prompt function allows selection of an item from a list of text items. The items are displayed in a box panel. Items are added to the list by previous calls to attach_box_item. |
| Parameters | message is a
null-terminated string with three components, separated by vertical bars ('|'), as
follows:
where:
buf is a character buffer into which the selected item, if any, will be copied. sort_flag, if non-zero, will cause the items to be sorted alphabetically; otherwise, they will retain the order in which they were received. |
| Return Value | If the user successfully selects an item, then the selection is copied into buf, and box_prompt returns 1; otherwise, 0 is returned. |
| Comments | The list of items used by box_prompt is freed before it returns. |
| See Also | attach_box_item, box_prompt_multiple |
| Example | if ( box_prompt (
"Cities|*|Enter city", buf, 1 ) ) ... if ( box_prompt ( "Cities|*|*", buf, 0 ) ) |
box_prompt_multiple
int box_prompt_multiple
( char *message, int sort_flag )
char *message; // box_prompt messages
int sort_flag; // enables/disables item sorting
| Synopsis | #include
"silver.h" box_prompt_multiple is like box_prompt, except that multiple items may be selected from the list of text items. The items are displayed in a box panel. Items are added to the list by repeated calls to attach_box_item. Selected items may be retrieved by successive calls to get_generic. |
| Parameters | message is a
null-terminated string with three components, separated by vertical bars ('|'), as
described in box_prompt, except for the third component:
where:
sort_flag, if non-zero, will cause the items to be sorted alphabetically; otherwise, they will retain the order in which they were received. |
| Return Value | If the user successfully selects at least one item then box_prompt_multiple returns 1; otherwise, 0 is returned. |
| See Also | attach_box_item, box_prompt_multiple, get_generic |
| Example | attach_box_item (
"One" ); attach_box_item ( "Two" ); attach_box_item ( "Three" ); attach_box_item ( "Four" ); attach_box_item ( "Five" ); if (box_prompt_multiple("Numbers|Select
numbers|*", |
bt_close
int bt_close( int handle
)
int handle; // an open b-tree database handle
| Synopsis | #include
"silver.h" The bt_close function closes the index and data files associated with the b-tree database referenced by handle. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. |
| Return Value | If the operation is successful, bt_close returns 1, and otherwise 0. |
| See Also | bt_open |
bt_create_data
int bt_create_data( char
*file_name, int record_size )
char *file_name; // the name of the data file to create
int record_size; // size of each record
| Synopsis | #include
"silver.h" The bt_create_data function creates an empty b-tree database data file. |
| Parameters | file_name is a null-terminated string specifying the name of the file desired. record_size is the desired size in bytes of each record in the database; record_size must be greater than 10 bytes, and less than 4096 bytes. |
| Return Value | bt_create_data returns 1 if successful, and 0 otherwise. |
| See Also | bt_create_tree, bt_open |
bt_create_tree
int bt_create_tree( char
*file_name )
char *file_name; // name of the index file to create
| Synopsis | #include
"silver.h" The bt_create_tree function creates an empty b-tree database index file. |
| Parameters | file_name is a null-terminated string specifying the name of the file desired. |
| Return Value | bt_create_tree returns 1 if successful, and 0 otherwise. |
| See Also | bt_create_data, bt_open |
bt_delete
int bt_delete( int handle )
int handle; // an open b-tree database handle
| Synopsis | #include
"silver.h" The bt_delete function deletes a record and index entry pair from a b-tree data and index file pair. The entry deleted is the last accessed by a call to bt_next, bt_previous, bt_find, or bt_find2. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. |
| Return Value | bt_delete returns 1 if the delection was successful, and 0 otherwise. |
| See Also | bt_erase |
bt_erase
int bt_erase(int handle,
int record_number)
int handle; // an open b-tree database handle
int record_number; // sequential index of record to erase
| Synopsis | #include
"silver.h" The bt_erase function removes a record from the b-tree database data file specified by handle. The record is specified by record_number. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. record_number is a sequential record number. |
| Return Value | bt_erase returns 1 if the delection was successful, and 0 otherwise. |
| See Also | bt_delete |
| Example | Here is a simple example;
see B-tree Database for more information on the b-tree functions. int handle; |
bt_find
int bt_find( int handle,
char *key )
int handle; // an open b-tree database handle
char *key; // the key to search for
| Synopsis | #include
"silver.h" The bt_find function searches the b-tree database specified by handle for the entry matching key. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. key is a null-terminated text string that contains the key to search for. |
| Return Value | The record number of the first matching entry is returned. If handle is invalid, 0 is returned. |
| See Also | bt_find2 |
bt_find2
int bt_find2( int
handle, char *key, int record_number )
int handle; // an open b-tree database handle
char *key; // the key to search for
int record_number; // record number to search for
| Synopsis | #include
"silver.h" The bt_find2 function searches the b-tree database specified by handle for the entry matching key/record_number combination. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. key is a null-terminated text string that contains the key to search for. record_number is a sequential record number. |
| Return Value | The record number of the matching key is returned if the search is successful; and otherwise 0 is returned. |
| See Also | bt_find |
bt_flush
void bt_flush( void )
| Synopsis | #include
"silver.h" The bt_flush function flushes all b-tree database files to disk, ensuring that the files will be secure in the event of abnormal or unexpected program termination. |
bt_insert
int bt_insert( int
handle, char *key, int record_number )
int handle; // an open b-tree database handle
char *key; // the key to insert
int record_number; // where to insert it
| Synopsis | #include
"silver.h" The bt_insert function inserts a new entry, key, in the b-tree database index file designated by handle, for the record specified by record_number. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. key is the new key value to store in the index. record_number is the sequential record number, typically obtained by a previous call to bt_store. |
| Return Value | bt_insert returns 0 if the entry matches an existing entry, or if the record_number is less than or equal to 0; otherwise, 1 is returned. |
| See Also | bt_store |
| Example | Here is an example showing
the storage of a data record and the creation of an index entry for that record: int handle; |
bt_next
int bt_next( int handle,
char *key )
int handle; // an open b-tree database handle
char *key; // buffer to receive next key value
| Synopsis | #include
"silver.h" The bt_next function accesses the next entry in the b-tree database index associated with handle. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. key is a pointer to a character buffer large enough to hold the associated key value |
| Return Value | If the read marker is at the end of the index, bt_next returns 0; otherwise, bt_next moves to the next entry, copies its key value into key, and returns the record_number associated with that key. |
| Comments | bt_previous, bt_set_first, bt_set_last and bt_set_key may be used to position the read marker. |
| See Also | bt_previous, bt_set_first, bt_set_last, bt_set_key |
bt_open
int bt_open( char
*tree_file_name, char *data_file_name )
char *tree_file_name; // index file name
char *data_file_name; // data file name
| Synopsis | #include
"silver.h" The bt_open function opens a b-tree database index and data file pair and makes it available for use. |
| Parameters | tree_file_name and data_file_name are null-terminated strings that designate the names of files on disk. |
| Return Value | If the files are successfully opened, a non-zero handle is returned that may be used with the other b-tree functions; otherwise, 0 is returned. |
| Comments | A data file may be opened simultaneously with multiple index files; conversely, each index file should be opened only with a single data file. B-tree databases remain open until explicitly closed by bt_close. |
| See Also | bt_close |
bt_previous
int bt_previous( int
handle, char *key )
int handle; // an open b-tree database handle
char *key; // buffer to receive next key value
| Synopsis | #include
"silver.h" The bt_previous function accesses the previous entry in the b-tree database index associated with handle. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. key is a pointer to a character buffer large enough to hold the associated key value |
| Return Value | If the read marker is at the startof the index, bt_next returns 0; otherwise, bt_next moves to the previous entry, copies its key value into key, and returns the record_number associated with that key. |
| Comments | bt_previous, bt_set_first, bt_set_last and bt_set_key may be used to position the read marker. |
| See Also | bt_previous, bt_set_first, bt_set_last, bt_set_key |
bt_read
int bt_read( int handle,
int record_number, char *buf )
int handle; // an open b-tree database handle
int record_number; // the record number of the record to read
char *buf; // where to store the record data
| Synopsis | #include
"silver.h" The bt_read function retrieves the data from a record specified by record_number from the b-tree database designated by handle. The data is stores in buf. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. record_number is a sequential record number, as obtainable by a call to bt_find. buf is a pointer to a buffer where the record is to be stored, and and should be greater than or equal to the record size of the data file. |
| Return Value | bt_read stores the record data in buf and returns 1 if successful, and returns 0 if not. |
| See Also | bt_find, bt_write |
| Example | See the section on B-Trees
for more information on the b-tree functions. int handle; |
bt_set_first
int bt_set_first( int
handle )
int handle; // an open b-tree database handle
| Synopsis | #include
"silver.h" The bt_set_first function sets the read marker to the first entry in the b-tree database index associated with handle. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. |
| Return Value | bt_set_first returns 1 if the index is non-empty; and 0 otherwise. |
| Comments | bt_set_first is normally used in combination with bt_next. |
| See Also | bt_set_last, bt_set_key |
| Example | Here is a simple example; see B-tree Database
for more information on the b-tree functions: int handle; |
bt_set_key
int bt_set_key( int
handle, char *key )
int handle; // an open b-tree database handle
char *key; // key value used in search
| Synopsis | #include
"silver.h" The bt_set_key function positions the read marker if the b-tree database index associated with handle corresponding to the key value specified by key. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. key contains the key to search for. |
| Return Value | If key exists in the index, then bt_set_key will position the read marker to that location, and return 1; otherwise, the read marker will be positioned to the next higher location, and 0 will be returned |
| See Also | bt_next, bt_previous |
bt_set_last
int bt_set_last( int
handle )
int handle; // an open b-tree database handle
| Synopsis | #include
"silver.h" The bt_set_last function sets the read marker to the last entry in the b-tree database index associated with handle. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. |
| Return Value | bt_set_last returns 1 if the index is non-empty; and 0 otherwise. |
| Comments | bt_set_last is normally used in combination with bt_next. |
| See Also | bt_set_first, bt_set_key |
| Example Here is a simple example; see B-tree Database for more information on the b-tree functions: int handle; |
|
bt_store
int bt_store( int
handle, void *buf )
int handle; // an open b-tree database handle
void *buf; // new record data
| Synopsis | #include
"silver.h" The bt_store function creates a new record in the b-tree database data file associated with handle. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. buf is a pointer to a buffer containing the new record data; it is assumed that this buffer is at least as large as the database record size. |
| Return Value | bt_store returns the record number of the newly created record. |
| Comments | bt_insert is normally called after bt_store to add the index entry for the new record. |
| See Also | bt_insert |
bt_update
int bt_update( int
handle, char *key, int record_number )
int handle; // an open b-tree database handle
char *key; // new key value
int record_number; // new record number
| Synopsis | #include
"silver.h" The bt_update function updates the index entry for the last entry obtained via bt_next, bt_previous, bt_find or bt_find2. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. key is the new key value. record_number is the new sequential record number. |
| Return Value | bt_update returns 1 if successful, and 0 if not. |
bt_write
int bt_write( int handle, int
record_number, char *buf )
int handle; // an open b-tree database handle
int record_number; // the record number of the record to write
char *buf; // pointer to new record
| Synopsis | #include
"silver.h" The bt_write function writes a new record to the b-tree database file associated with handle at the location specified by record number. |
| Parameters | handle is an open b-tree database handle, as obtained by a call to bt_open. record_number is the sequential record number of the record. buf is a pointer to a buffer containing the new record; it is assumed that this buffer is at least as large as the database record size |
| Return Value | bt_write returns 1 if successful, and 0 if not. |
| See Also | bt_read |
c_to_w
void c_to_w ( SS_XYZ
*p1, SS_XYZ *p2 )
SS_XYZ *p1; // a C-space point
SS_XYZ *p2; // a W-space point
| Synopsis | #include
"silver.h" The c_to_w function converts a point from C-space to W-space coordinates. |
| Parameters | p1 and p2 are both pointers to SS_XYZ structs. |
| Return Value | none; the result is stored into p2. |
| Comments | w_to_c is the inverse of c_to_w. |
| See Also | w_to_c |
| Example | Note that c_to_w ( &p1,&q1 ); produces the same result as: ss_command ( "draw line [%z] [%z]", &q1, &q2 ); |
chdir
int chdir ( char *path )
char *path; // directory name
| Synopsis | #include
"silver.h" The chdir function changes the current working directory to the directory specified by path. The default drive is not changed. |
| Parameters | path is a null-terminated string indicating the desired new working directory. |
| Return Value | chdir returns 0 if the working directory was successfully changed. If an error occurs, chdir returns -1, and the systen error variable errno is set to ENOENT. |
| Comments | chdir does not modify the SilverScreen directories (as obtained by path_home, path_silver, path_drawing, path_exection, path_library). |
| See Also | getcwd, mkdir, rmdir |
clear_area
void clear_area ( int top,
int left, int bottom, int right, int color )
int top; // top of area
int left; // left side of area
int bottom; // bottom of area
int right; // right side of area
int color; // color to use
| Synopsis | #include
"silver.h" The clear_area function clears the indicated area on the screen with the specified color. |
| Parameters | The top, left,
bottom and right parameters all specify character locations on the
screen, with 1 <= top <= bottom <= schar_height and 1 <= left <= right <= schar_width The color parameter is a color number. |
| See Also | pixel_clear |
clear_away_lines
void clear_away_lines (
void )
| Synopsis | #include
"silver.h" The clear_away_lines function frees the memory used by any graphics lines that were saved by calling a paint function (paint_primitive, paint_entity) with the value COLOR_INVERSE or'ed into its color argument. clear_away_lines provides a means by which the memory used by these lines may be reclaimed without refreshing the lines on the screen. |
| See Also | refresh_lines, paint_primitive, paint_entity |
clear_icons
void clear_icons ( void
)
| Synopsis | #include
"silver.h" The clear_icons function clears the area where icons are displayed. |
clear_window
void clear_window ( void
)
| Synopsis | #include
"silver.h" The clear_window function causes the current window to be cleared to its current background setting (either solid color or textured). |
collect_generic
int collect_generic ( int g_type,
char *aux_string )
int g_type;
//
generic type
char *aux_string; // auxiliary string
| Synopsis | #include
"silver.h" The collect_generic function assembles an internal list of SilverScreen items specified by g_type. The items of this list may be accessed by get_generic. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Parameters | g_type specifies the
type of data to collect. aux_string is an auxiliary string appropriate to g_type.
g_type may take on the following values (as defined in silver.h); any use of
aux_string is noted:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Return Value | collect_generic returns the number of items collected. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See Also | get_generic |
color_of_edge
int color_of_edge (
OBJECT_NODE *obj, int i )
OBJECT_NODE *obj; // pointer to SilverScreen object node
int i; // edge number
| Synopsis | #include
"ssnodes.h" The color_of_edge function returns the color of the ith edge in the object pointed to by obj. |
| Parameters | obj is a pointer to a SilverScreen object node, as obtained by a call to get_bos. i is an edge number. |
| Return Value | The number returned is a color index. i.e. a number between 0 and 255 |
| See Also | rgb_of_edge, color_to_rgb |
color_to_rgb
void color_to_rgb ( int
color, int *r, int *g, int *b)
int color; // color number
int *r; // pointer to int to receive red value
int *g; // pointer to int to receive green value
int *b; // pointer to int to receive blue value
| Synopsis | #include
"silver.h" The color_to_rgb function retrieves the red, green and blue values associated with the color number specified by color. |
| Parameters | color is a color number (i.e. between 0 and 255). r, g and b are all pointers to integer locations that are to receive the red, green and blue values. |
| See Also | rgb_to_color |
congruent
int congruent ( char *obj1, char
*obj2 )
char *obj1; // path to SilverScreen object
char *obj2; // path to SilverScreen object
| Synopsis | #include
"silver.h" The congruent function determines whether the objects specified by obj1 and obj2 are identical. |
||||||||||||||||||
| Parameters | obj1 and obj2 are both null-terminated strings containing the full paths to SilverScreen objects. | ||||||||||||||||||
| Return Value | congruent returns one
of the following values (as defined in silver.h):
|
||||||||||||||||||
| Comments | The objects must be valid solids. |
count_windows
int count_windows ( void
)
| Synopsis | #include
"silver.h" The count_windows function returns the number of windows in the current screen. |
| Return Value | The number of windows. |
cross_product
void cross_product (
SS_XYZ *xyz1, SS_XYZ *xyz2, SS_XYZ *xyz3, SS_XYZ *cross )
SS_XYZ *xyz1; // a pointer to a 3D point
SS_XYZ *xyz2; // a pointer to a 3D point
SS_XYZ *xyz3; // a pointer to a 3D point
SS_XYZ *cross; // the result, a pointer to a 3D point
| Synopsis | #include
"silver.h" The cross_product function computes the cross-product of the three points at xyz1, xyz2 and xyz3. The cross-product is computed by the following calculation: cross->x = xyz1->y *
(xyz2->z - xyz3->z) + |
| Parameters | xyz1, xyz2, xyz3 and cross are all pointers to SS_XYZ structures. |
| Return Value | none; the result is stored into cross. |
| See Also | dot_product |
cv_get
int cv_get ( int variable )
int variable; // control variable specifier
| Synopsis | #include
"silver.h" The cv_get function returns the value of the control variable represented by variable. |
| Parameters | variable is an integer that specifies the control variable. |
| Return Value | The value of the specified control variable. |
| See Also | cv_set, also see Control Variables for more detailed information on control variables. |
cv_set
void cv_set ( int variable, int
setting )
int variable; // control variable specifier
int setting; // new setting
| Synopsis | #include
"silver.h" The cv_set function sets the control variable variable to setting. |
| Parameters | variable is an integer indicating which control variable is desired. setting is an integer, appropriate to the control variable selected. Possible values for variable are listed in the entry for cv_get; note that not all control variables available to cv_get may be set by cv_set. |
| See Also | cv_get, also see Control Variables for more detailed information on control variables. |
dcos
double dcos( double x )
double x; /* angle in degrees */
| Synopsis | #include
"math.h" The dcos function returns the cosine of x , for x in degrees. |
| Parameters | x may be any double value. |
| Return Value | cos returns a value in the range of [-1, 1]. |
| See Also | acos , dsin |
delta_worldx
void delta_worldx ( double
delta )
double delta; // amount to change worldx
| Synopsis | #include
"silver.h" The delta_worldx function increments the predefined SilverC variable worldx by the amount delta. |
| Parameters | delta may be any amount. |
| Comments | delta_worldx was called dx until version 4.50. |
| See Also | delta_worldy, delta_worldz |
delta_worldy
void delta_worldy ( double delta
)
double delta; // amount to change worldy
| Synopsis | #include
"silver.h" The delta_worldy function increments the predefined SilverC variable worldy by the amount delta. |
| Parameters | delta may be any amount. |
| Comments | delta_worldy was called dy until version 4.50. |
| See Also | delta_worldx, delta_worldz |
delta_worldz
void delta_worldz ( double delta
)
double delta; // amount to change worldx
| Synopsis | #include
"silver.h" The delta_worldz function increments the predefined SilverC variable worldz by the amount delta. |
| Parameters | delta may be any amount. |
| Comments | delta_worldz was called dz until version 4.50. |
| See Also | delta_worldx, delta_worldy |
display_icon
void display_icon ( char
*title, char *name, int mask, int rows, int cols )
char *title; // text for title bar
char *name; // icon drawing name
int mask; // bit-mask that selects the icon
int rows; // number of icon rows
int cols; // number of icon columns
| Synopsis | #include
"silver.h" The display_icon function displays a single icon in the icon area. |
| Parameters | name is the name of the drawing in which the icons are stored. mask selects which icon is to be displayed: if bit 3 of mask is 1, then the entity "icon3" from drawing name will be used as the icon. rows and cols specify the number of rows and columns in the icon area. |
| See Also | clear_icons, icon, icon2 |
| Example |
int n; if ( n = icon ( "Title","choice", 8, 1, 0 ) ) { display_icon ("Title","choice",1L<<(n - 1),8,1); switch ( n ) { ... } } |
dot_product
double dot_product (
SS_XYZ *xyz1, SS_XYZ *xyz2 )
SS_XYZ *xyz1; // a pointer to a 3D point
SS_XYZ *xyz2; // a pointer to a 3D point
| Synopsis | #include
"silver.h" The dot_product function computes the dot product of the two points at xyz1 and xyz2. The dot product is computed by the following calculation: result = p1->x * p2->x + |
| Parameters | xyz1 and xyz2 are pointers to a SS_XYZ structures. |
| Return Value | The result of the specified computation is returned. |
| See Also | cross_product |
draw_line
void draw_line ( int x1, int y1,
int x2, int y2, int color )
int x1; // x value of point 1
int y1; // y value of point 1
int x2; // x value of point 2
int y2; // y value of point 2
int color; // color to use
| Synopsis | #include
"silver.h" The draw_line function draws a line on the graphics screen in the specified color, between the points with screen pixel coordinates (x1, y1) and (x2, y2). |
|||||||||
| Parameters | x1, y1,
x2 and y2 are all integers, such that 0 <= x1, x2
< spixel_width and 0 <= y1, y2 < spixel_height. color
is a color number in the range of 0 to 255, which may have the following flags or'ed in
(as defined in silver.h):
|
|||||||||
| See Also | draw_point, draw_world_line, draw_world_point, refresh_lines, clear_away_lines |
draw_polygon
int draw_polygon ( int
count, XYZ *points )
int count; // number of points in the polygon
XYZ *points; // address of array of points definintg the polygon
| Synopsis | #include
"silver.h" The draw_polygon function adds a polygon to the drawing database in the current object. |
| Parameters | count is an integer specifying the number of points in the polygon; points is the address of an array of XYZs specifying the points of the polygon. |
| Return Value | draw_polygon returns FALSE if the number of points in the polygon is greater than 100, or a memory allocation fails in the process of building the polygon; otherwise, TRUE is returned. |
| Comments | draw_polygon is
intended as a faster replacement to the script command sequence:
|
| See Also | draw_triangle, draw_quad |
draw_quad
int draw_quad ( XYZ *pt1, XYZ
*pt2, XYZ *pt3, XYZ *pt4 )
XYZ *pt1; // address of first point of polygon
XYZ *pt2; // address of second point of polygon
XYZ *pt3; // address of third point of polygon
XYZ *pt4; // address of fourth point of polygon
| Synopsis | #include
"silver.h" The draw_quad function adds a four-sided polygon to the drawing database in the current object. |
| Parameters | pt1, pt2, pt3 and pt4 are the addresses of the first, second, third and fourth points in the polygon, respectively. |
| Return Value | draw_quad returns FALSE if a memory allocation fails in the process of building the polygon; otherwise, TRUE is returned. |
| Comments | draw_quad is intended
as a faster replacement to the script command sequence:
|
| See Also | draw_triangle, draw_polygon |
draw_rgb_line
void draw_rgb_line ( int x1,int
y1,int x2,int y2,RGB rgb,int width )
int x1; // x value of point 1
int y1; // y value of point 1
int x2; // x value of point 2
int y2; // y value of point 2
RGB rgb; // color to use
int width; // line width
| Synopsis | #include
"silver.h" The draw_line function draws a line on the graphics screen in the specified rgb color, between the points with screen pixel coordinates (x1, y1) and (x2, y2). |
| Parameters | x1, y1, x2 and y2 are all integers, such that 0 <= x1, x2 < spixel_width and 0 <= y1, y2 < spixel_height. rgb is an rgb color as constructed by MAKE_RGB. width is the integer width of the line. |
| See Also | draw_point, draw_world_line, draw_world_point, refresh_lines, clear_away_lines |
draw_rgb_pixel
void draw_rgb_pixel (
int x1, int y1, RGB rgb )
int x1; // x value of point 1
int y1; // y value of point 1
RGB rgb; // color to use
| Synopsis | #include
"silver.h" The draw_line function draws a pixel on the graphics screen in the specified rgb color at the pixel coordinates (x1, y1). |
| Parameters | x1 and y1 are integers, such that 0 <= x1 < spixel_width and 0 <= y1 < spixel_height. rgb is an rgb color as constructed by MAKE_RGB. |
| See Also | draw_point, draw_world_line, draw_world_point, refresh_lines, clear_away_lines |
draw_triangle
int draw_triangle ( XYZ
*pt1, XYZ *pt2, XYZ *pt3, XYZ *pt4 )
XYZ *pt1; // address of first point of polygon
XYZ *pt2; // address of second point of polygon
XYZ *pt3; // address of third point of polygon
| Synopsis | #include
"silver.h" The draw_triangle function adds a three-sided polygon to the drawing database in the current object. |
| Parameters | pt1, pt2 and pt3 are the addresses of the first, second and third points in the polygon, respectively. |
| Return Value | draw_triangle returns FALSE if a memory allocation fails in the process of building the polygon; otherwise, TRUE is returned. |
| Comments | draw_triangle
is intended as a faster replacement to the script command sequence:
|
| See Also | draw_quad, draw_polygon |
draw_world_line
void draw_world_line (
SS_XYZ *p1, SS_XYZ *p2, int color )
SS_XYZ *p1; // world point 1
SS_XYZ *p2; // world point 2
int color; // color to use
| Synopsis | #include
"silver.h" The draw_world_line function draws a line on the screen in the specified color, between the two world points specified by p1 and p2. |
|||||||||
| Parameters | p1 and p2 are
the addresses of two SS_XYZs, representing two points in world space. color is a color number in the range of 0 to 255, which may have the following flags or'ed in (as defined in silver.h):
|
|||||||||
| Comments | The 2D projection of the 3D line between the points may not lie within the bounds of the current window. | |||||||||
| See Also | draw_line, draw_point, draw_world_point, refresh_lines, clear_away_lines |
draw_world_line_rgb
void draw_world_line_rgb ( SS_XYZ
*p1, SS_XYZ *p2, RGB rgb, int mode )
SS_XYZ *p1; // world point 1
SS_XYZ *p2; // world point 2
RGB rgb; // rgb to use
int mode; // width and inverse control
| Synopsis | #include
"silver.h" The draw_world_line function draws a line on the screen in the specified color, between the two world points specified by p1 and p2. |
|||||||||
| Parameters | p1 and p2 are
the addresses of two SS_XYZs, representing two points in world space.rgb is
an rgb color number as constructed by MAKE_RGB. mode may have the following
flags or'ed in (as defined in silver.h):
|
|||||||||
| Comments | The 2D projection of the 3D line between the points may not lie within the bounds of the current window. | |||||||||
| See Also | draw_line, draw_point, draw_world_point, refresh_lines, clear_away_lines |
draw_world_point
void draw_world_point (
SS_XYZ *p, int color )
SS_XYZ *p; // a world point
int color; // color to use
| Synopsis | #include
"silver.h" The draw_world_point function draws a pixel on the screen in the specified color, at the point specified by the world point p. |
|||||||||
| Parameters | p is the address of
an SS_XYZ, representing a point in world space. color is a color
number in the range of 0 to 255, which may have the following flags or'ed in (as defined
in silver.h):
|
|||||||||
| Comments | The 2D projection of the 3D point may not lie within the bounds of the current window. | |||||||||
| See Also | draw_line, draw_point, draw_world_line, refresh_lines, clear_away_lines |
dsin
double dsin( double x )
double x; /* angle in degrees */
| Synopsis | #include
"math.h" The dsin function returns the sine of x , for x in radians. |
| Parameters | x is in degrees and may be any double value. |
| Return Value | dsin returns a value in the range [-1, 1]. |
| See Also | asin , dsin |
dtan
double dtan( double x )
double x; // angle in degrees
| Synopsis | #include
"math.h" The dtan function calculates the tangent of x , for x in degrees. |
| Parameters | x may be any double value. |
| Return Value | dtan returns the tangent of x . |
| See Also | dsin , dcos , atan , atan2 |
equal_double
int equal_double ( double x,
double y )
double x; // any double value
double y; // any double value
| Synopsis | #include
"silver.h" The equal_double function tests whether two double values are regarded as equal to SilverScreen. That means that the two quantities are within epsilon (the system equality threshold) of each other. |
| Parameters | x and y may be any double values. |
| Return Value | equal_double returns 1 if the two quantities are within epsilon of each other, and 0 if not. |
error_message
void error_message ( char
*message, ... )
char *message; // message or format string
| Synopsis | #include
"silver.h" The error_message function displays the error message designated by message, and waits for the user to acknowledge the message. This is the standard way for displaying errors in SilverScreen. |
| Parameters | message is a null-terninated string, possibly containing printf-style format specifiers. If specifiers appear, they must be matched in number and type to subsequent arguments to error_message. |
| Comments | The types of arguments must match those expected by the format specifiers in fmt, and the number of arguments must be greater than or equal to the number of specifiers in fmt; otherwise, the result of error_message is undefined. fprintf contains a description of format specifiers acceptable to error_message. |
error_text
char *error_text ( int
error_number, char *buf )
int error_number; // SilverScreen error number
char *buf; // address of buffer to receive text
| Synopsis | #include
"silver.h" The error_text function copies the text string that SilverScreen associates with the error number error_number into buf. error_number is as obtained by ss_errno, the SilverScreen error number. |
| Parameters | error_number is any valid SilverScreen error number. buf is the address of a character array, which should be at least 80 characters in length. |
| Return Value | error_text returns buf. |
eval_expression
double eval_expression (
char *str )
char *str; // SilverScreen expression string
| Synopsis | #include
"silver.h" The eval_expression function evaluates str as a numeric SilverScreen expression. |
| Parameters | str is a null-terminated string containing the numeric expression. |
| Return Value | The result of the evaluation is returned. |
| Comments | Expressions are evaluated as described in the SilverScreen Reference Manual. |
extents
int extents ( char
*path, SS_XYZ *high, SS_XYZ *low)
char *path; // path to SilverScreen primitive or entity
SS_XYZ *high; // address of upper extents
SS_XYZ *low; // address of lower extents
| Synopsis | #include
"silver.h" The extents function computes the extents of a SilverScreen primitive or entity. The computed upper and lower extents are stored into the 3D points pointed to by high and low, respectively. |
| Parameters | path is a null-terminated string containing the name of the primitive of entity. high and low are addresses of 3D points that are to receive the upper and lower extents of the primitive or entity. |
| Return Value | extents returns 1 if the item referred to by path exists in the current drawing, and 0 otherwise. |
| See Also | bos_extents |
fence_pgroup
int fence_pgroup ( char
*message, int p_type )
char *message; // prompt message
int p_type; // prompt type
| Synopsis | #include
"silver.h" The fence_pgroup function displays message, and then permits a p-group of primitives to be interactively selected using a fence. p_type designates the allowable types that are considered for selection. Primitives allowed by p_type that are wholly inside the fence are placed in the p-group list. |
|||||||||||||||||||||||||||||||||||||||
| Parameters | message is a
null-terminated string containing the message to be used in prompting, p_type
is an integer value containing flags indicating which primitive types are to be
considered. p_type may be composed of any of the following flags or'ed together (as
defined in silver.h):
|
|||||||||||||||||||||||||||||||||||||||
| Return Value | fence_pgroup returns 1 if the user successfully completes the fencing operation, and 0 if not. | |||||||||||||||||||||||||||||||||||||||
| Comments | The paths to the primitives selected by fence_pgroup may be accessed by use of get_group_item. | |||||||||||||||||||||||||||||||||||||||
| See Also | prompt_pgroup, fence_qgroup, get_group_item | |||||||||||||||||||||||||||||||||||||||
| Example | Here
is an example of how to use fence_pgroup in conjunction with get_pgroup_item: if (
fence_pgroup("Select polygons",P_POLYGON)) |
fence_qgroup
int fence_qgroup ( char
*message, int e_type )
char *message; // prompting message
int e_type; // entity type mask
| Synopsis | #include
"silver.h" The fence_qgroup function displays message, and then permits a q-group of entities to be interactively selected using a fence. e_type designates the allowable entity type that is considered for selection. Entities of this type that are wholly inside the fence are placed in the q-group list. |
||||||||||||||||||
| Parameters | message is a
null-terminated string containing the message to be used in prompting, e_type
is an integer value containing flags indicating which entity type is to be considered. e_type
may be one of (as defined in silver.h):
|
||||||||||||||||||
| Return Value | fence_qgroup returns 1 if the user successfully completes the fencing operation, and 0 if not. | ||||||||||||||||||
| Comments | The paths to the entities selected by fence_qgroup may be accessed by use of get_qgroup_item. | ||||||||||||||||||
| See Also | prompt_qgroup, fence_pgroup, get_qgroup_item | ||||||||||||||||||
| Example | Here is an example of how to
populate a q-group using fence_qgroup, and how to access the members using get_group_item
(remember that the group name "" refers to the q-group): if ( fence_qgroup( |
fetch_tag
int fetch_tag ( char
*path_bos, char *tag_name, SS_TAG *tag )
char *path_bos; // path name of SilverScreen block, object or symbol
char *tag_name; // tag name
SS_TAG *tag; // address of tag structure
| Synopsis | #include
"silver.h" The fetch_tag function searches the SilverScreen database for a block, object or symbol with the name path_bos, containing a tag with the name tag_name. If such a BOS exists, then its tag contents are copied into the structure pointed to by tag. |
||||||||
| Parameters | path is a
null-terminated string containing the name of the block, object or symbol desired. tag_name
is a null-terminated string containing the tag name desired. tag is the
address of a tag structure (defined in silver.h) to receive the tag information. SS_TAG has the following structure and uses the following definitions: #define T_VALUE 1 The type of value returned is dependent on type, and may be accessed by use of the appropriate member of SS_TAG, as shown here:
|
||||||||
| Return Value | fetch_tag copies the tag information into tag if the search succeeds, and returns SS_SUCCESS (0); otherwise SS_NOTFOUND (-1) is returned. | ||||||||
| Comments | The TAG script command is used to attach tagged data. There is no SilverC function that attaches tags to entities. |
file_date
char *file_date ( char
*name, char *buf )
char *name; // name of file on disk
char *buf; // character array to receive date string
| Synopsis | #include
"silver.h" The file_date function retrieves the last modification date of a file on disk, whose name as given by name. The date is returned in buf as a null-terminated string, formatted as "dd/mm/yy". |
| Parameters | name is a null-terminated string specifying the name of the disk file. buf is the address of a character buffer that is to receive the date string. |
| Return Value | file_date returns NULL if the file does not exist, or if some other error occurs. Otherwise, file_date returns buf. |
| See Also | file_time |
file_time
char *file_time ( char
*name, char *buf )
char *name; // name of file on disk
char *buf; // character array to receive time string
| Synopsis | #include
"silver.h" The file_time function retrieves the last modification time of a file on disk, whose name as given by name. The date is returned in buf as a null-terminated string, formatted as "hh:mm:ss". |
| Parameters | name is a null-terminated string specifying the name of the disk file. buf is the address of a character buffer that is to receive the time string. |
| Return Value | file_time returns NULL if the file does not exist, or if some other error occurs. Otherwise, file_time returns buf. |
| See Also | file_date |
find_first
int find_first ( char
*path, char *buf )
char *path; // file specification pattern
char *buf; // character buffer to receive filename
| Synopsis | #include
"silver.h" The find_first function searches the disk for a file matching the file pattern path (which is potentially wildcarded with * or ? characters), and copies the first such filename into buf. Further matches may be retrieved by using find_next. |
|||||||||||||||||||||||||||
| Parameters | path is a null-terminated string, containing the file pattern. buf is the address of a character buffer, sufficiently large enough to hold a filename. | |||||||||||||||||||||||||||
| Return Value | find_first returns 0
if no matching file was found; otherwise, the following values are returned:
Further, these return values may have the following values or'ed in:
|
|||||||||||||||||||||||||||
| See Also | find_next |
find_next
int find_next ( char
*buf )
char *buf; // character buffer to receive filename
| Synopsis | #include
"silver.h" The find_next function retrieves matching filenames based on the pattern used in a previous call to find_first, copying them into buf. |
| Parameters | buf is the address of a character buffer, sufficiently large enough to hold a filename. |
| Return Value | find_next returns values as specified in find_first. |
| See Also | find_first |
void follow_vector ( SS_XYZ *p1,
SS_XYZ *p2, double d, SS_XYZ *q )
SS_XYZ *p1; // first point of vector
SS_XYZ *p2; // second point of vector
double d; // distance
SS_XYZ *q; // resulting point
| Synopsis | #include
"silver.h" On the line defined by p1-p2, this function finds, for a positive value d, a point q that lies a distance d from p1 in the direction of p2. For negative values of d, the function finds a point q opposite the direction of p2. |
| Parameters | p1, p2 are distinct points; d is any value. |
format_double
char *format_double (
double val,char *buf,int notation,int measure )
double val; // a double value
char *buf; // character buffer to receive formatted value
int notation; // notation selector
int measure; // unit of measurement selector
| Synopsis | #include
"silver.h" The format_double function formats the double value specified by val into the char character buffer pointed to by buf, subject to notation and measurement. |
||||||||||||||||||||||||||
| Parameters | val is any double
value. buf is the address of a character buffer. notation is one of the
following values (defined in silver.h):
measure may be one of the following (defined in silver.h):
|
||||||||||||||||||||||||||
| Return Value | format_double returns buf. | ||||||||||||||||||||||||||
| See Also | cv_get, cv_set to obtain or modify current notation and units of measure settings. |
get_bos
BOS_NODE *get_bos ( char
*path )
char *path; // path to block, object or symbol
| Synopsis | #include
"ssnodes.h" The get_bos function searches a SilverScreen drawing for the entity specified by path. |
| Parameters | path is a null-terminated string containing the name of an entity. |
| Return Value | get_bos returns a pointer to the entity, if found, and NULL otherwise. |
| Comments | The pointer returned is a direct pointer into the SilverScreen drawing database. |
| See Also | make_path, get_prim |
get_cspace
void get_cspace ( SS_XYZ
*vert, SS_XYZ *base, SS_XYZ *horz )
SS_XYZ *vert; // address of 3D point to receive y-axis direction
SS_XYZ *base; // address of 3D point to receive c-space origin
SS_XYZ *horz; // address of 3D point to receive x-axis direction
| Synopsis | #include
"silver.h" The get_cspace function determines a point and two directions that define the current construction space. |
| Parameters | vert is the address of a 3D point that is to receive the y-axis direction. base is the address of a 3D point that is to receive the c-space origin. horz is the address of a 3D point that is to receive the x-axis direction. |
get_direct_pointer
char *get_direct_pointer
( int which_pointer )
int which_pointer; // SilverScreen variable
| Synopsis | #include
"silver.h" #include "ssnodes.h" The get_direct_pointer function retrieves a pointer to the specified SilverScreen variable, represented by which_pointer. |
| Parameters | which_pointer is an integer that determines the type of pointer requested. Direct pointer variables are defined in silver.h:DP_LIGHT_LIST 1 retrieve pointer to first LIGHT_NODE structure in drawing |
| Return Value | get_direct_pointer returns the given pointer, if the variable exists, and NULL if not. |
get_drive
void get_drive ( int
*current_drive )
int *current_drive; // address of integer to receive disk drive number
| Synopsis | #include
"silver.h" The get_drive function obtains the current disk drive number. The current drive is copied into the integer pointed to by current_drive, with values as specified by 1 = drive A, 2 = drive B, 3 = drive C, and so on. |
| Parameters | current_drive is the address of an integer to receive the disk drive number. |
get_endpoints
void get_endpoints (
PRIM_NODE *prim, SS_XYZ *p1, SS_XYZ *p2 )
PRIM_NODE *prim; // primitive node pointer
SS_XYZ *p1; // address of 3D point to receive first endpoint
SS_XYZ *p2; // address of 3D point to receive second endpoint
| Synopsis | #include
"ssnodes.h" The get_endpoints function retrieves the endpoints of the line or arc pointed to by prim. |
| Parameters | prim is a primitive node pointer, as obtained by get_prim. p1 and p2 are addresses of 3D points that are to receive the endpoints. |
| See Also | get_prim |
get_env
int get_env ( char *var,
char *buf )
char *var; // environment variable name
char *buf; // character buffer to receive environment string
| Synopsis | #include
"silver.h" The get_env function copies the environment string associated with the environment variable var into the character buffer pointed to by buf. |
| Parameters | var is a null-terminated string containing the name of the environment variable. buf is a character buffer that is to receive the associated environment string. |
| Return Value | get_env copies the associated environment string into buf, and returns 1 if an environment variable with the name var exists, and otherwise 0. |
| See Also | getenv |
get_event_info
int get_event_info (
SS_EVENT *event );
SS_EVENT *event; // address of a SilverScreen event structure
| Synopsis | #include
"silver.h" The get_event_info function is used to return information about various SilverScreen events that may not be contained in the return value from inchar. The event information is returned in the SS_EVENT structure pointed to by event. The id, flags, mouse_x and mouse_y fields of the SS_EVENT structure are always filled after inchar. Other fields are filled only on certain events:
|
|||||||||||||||
| Parameters | event is the address
of an SS_EVENT structure used to receive the event information. The SS_EVENT structure takes the following form: typedef struct |
|||||||||||||||
| Return Value | get_event_info returns 0 always. | |||||||||||||||
| Comments | The event information is only valid after a call to inchar, event information returned after a call to nextkey will not be reliable. | |||||||||||||||
| See Also | menu_persist, icon_persist, icon2_persist |
get_generic
int get_generic ( int i,
char *buf )
int i; // generic element number
char *buf; // character buffer to receive generic data
| Synopsis | #include
"silver.h" The get_generic function returns the i-th element of the list created by the last use of collect_generic. |
| Parameters | i is an integer greater than 0. buf is the address of a character buffer that is to receive the value of the generic data. |
| Return Value | get_generic copies the associated generic data item into buf if the list contains at least i items, and returns 1; otherwise, get_generic returns 0. |
| See Also | collect_generic |
get_group
int get_group ( int
count, char *name )
int count; // group index number
char *name; // character buffer to receive group name
| Synopsis | #include
"silver.h" The get_group function allows retrieval of the names of all currently defined groups. |
| Parameters | count is the group index number, 1 to the number of groups. name is the address of a character buffer that is to receive the associated group name. |
| Return Value | get_group copies the name of the associated group into name if count is a valid group number, and then returns 1; otherwise, get_group returns 0. |
| See Also | get_group_item |
get_group_item
int get_group_item ( char
*gname, int count, char *buf )
char *gname; // group name
int count; // group item index number
char *buf; // character buffer to receive group item path
| Synopsis | #include
"silver.h" The get_group_item function allows retrieval of entity paths within a named group or the q-group. |
| Parameters | For a named group, gname is a null-terminated string containing the name of the group. For a q-group, gname is the empty string (""). count is the index number of the item in the group designated by gname, 1 to the number of items in the group. buf is the address of a character buffer that is to receive the entity path. |
| Return Value | get_group_item copies the entity path into buf if the group associated with gname exists, and there are at least count items in the group, and then returns 1, otherwise get_group_item returns 0. |
| Comments | The empty string ("", not NULL) may be used to designate the q-group. |
| See Also | get_group, get_pgroup_item |
get_pattern_info
int get_pattern_info (
char *name, SS_PATTERN *pat )
char *name; // pattern name
SS_PATTERN *pat; // address of SS_PATTERN to receive result
| Synopsis | #include
"silver.h" The get_pattern_info function retrieves pattern information for a given pattern name. |
| Parameters | name is the name of a pattern. pat is the address of an SS_PATTERN structure that is to receive the pattern information. |
| Return Value | get_pattern_info returns 1 if the pattern name is found; otherwise 0. |
get_pgroup_item
int get_pgroup_item (
int count, char *buf )
int count; // primitive ID number
char *buf; // character buffer to receive primitive name
| Synopsis | #include
"silver.h" The get_pgroup_item function retrieves the primitive with index number count from the p-group. |
| Parameters | count is the index number of the primitive in the p-group, 1 to the number of items in the group. buf is the address of a character buffer that is to receive the primitive name. |
| Return Value | get_pgroup_item the primitive name into buf if the there are at least count items in the p-group, and then returns 1, otherwise get_pgroup_item returns 0. |
| See Also | get_pgroup_item |
get_plane
int get_plane (SS_XYZ
*xyz1,SS_XYZ *xyz2,SS_XYZ *xyz3,SS_COEF *coef)
SS_XYZ *xyz1; // address of a 3D point
SS_XYZ *xyz2; // address of a 3D point
SS_XYZ *xyz3; // address of a 3D point
SS_COEF *coef; // address of plane structure to receive result
| Synopsis | #include
"silver.h" The get_plane function computes the plane equation Ax + By + Cz + D = 0 of the plane formed by points p1, p2 and p3. The plane equation is placed in the coefficient structure coef, where the x, y and z members of coef->abc specifies the A, B and C components of the equation, and coef->d specifies the constant D. |
| Parameters | xyz1, xyz2 and xyz3 are 3D points that specify the plane. coef is the address of the SS_COEF structure that is to receive the plane coefficients. |
| Return Value | If the points do not specify a plane, get_plane returns 0, and coef is unmodified; otherwise, get_plane returns 1. |
| Comments | The plane equation returned in coef is normalized. |
get_prim
PRIM_NODE *get_prim ( char *path,
OBJECT_NODE **obj )
char *path; // path name of primitive
OBJECT_NODE **obj; // address of pointer to object structure
| Synopsis | #include
"ssnodes.h" The get_prim function returns a pointer to the primitive located at path. It also sets obj to the object node that contains the primitive. |
| Parameters | path is a null-terminated string that contains the name of the primitive. obj is the address of a pointer to an OBJECT_NODE that is to receive the object structure address. |
| Return Value | get_prim returns 1 if the specified primitive is found, and obj is updated; otherwise get_prim returns 0. |
| Comments | The pointer returned is a direct pointer into the SilverScreen drawing database. |
| See Also | get_bos |
get_printer_info
void get_printer_info (
SS_PRINTER_INFO *pi );
SS_PRINTER_INFO *pi; // pointer to printer information structure
| Synopsis | #include
"silver.h" The get_printer_info function returns information for the currently selected SilverScreen printer. |
||||||||||||
| Parameters | pi is the address of
an SS_PRINTER_INFO structure used to receive the printer information. The SS_PRINTER_INFO structure takes the following form:
Fields in the SS_PRINTER_INFO structure:
|
||||||||||||
| Comments | The IsColorDevice field has proven to be somewhat misleading for printers like the HP DeskJet 600C when the black cartridge is loaded. The 600C reports itself as a color device because it can perform gray-scaling. |
get_proplib_entry
int get_proplib_entry (
char *proplib_name, char *entry_name, PROPLIB_ENTRY *ple )
char *proplib_name; // name of property library
char *entry_name; // name of entry in property library
PROPLIB_ENTRY *ple; // address to return result
| Synopsis | #include
"ssnodes.h" The get_proplib function allows retrieval of the property information for the entry entry_name within the property library proplib_name. |
| Parameters | proplib_name is the name of a property library. entry_name is the name of an entry within this library. ple is the address of a PROPLIB_ENTRY structure that is to receive the tag name. |
| Return Value | get_proplib_entry copies the entry information into ple and returns 1 if the entry specified by proplib_name and and entry_name is found; otherwise, 0 is returned, and no copy is performed. |
| Comments | See ssnodes.h for a description of this structure. |
get_ss_variable_value
int
get_ss_variable_value ( int select )
int select; // value identifier
| Synopsis | #include
"silver.h" The get_ss_variable_value function allows retrieval of values relevant to the current window configuration. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Parameters | select is a value that selects which variable’s value is to be returned. The possible values for select are as follows (defined in silver.h): | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Return Value | get_ss_variable_value returns the specified value. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Comments | get_ss_variable_value
is mostly relevant to use in the SilverEngine, to allow use of the identifiers char_height,
etc. to be used directly, in a way compatible with SilverC and REX applications.
|
get_tag
int get_tag ( char
*bos_name, int count, char *buf )
char *bos_name; // name of a block, object or symbol
int count; // tag index number
char *buf; // character buffer to receive tag name
| Synopsis | #include
"silver.h" The get_tag function allows retrieval of tag names from the current drawing. |
| Parameters | bos_name is the name of a block, object or symbol in the current drawing. count is the index number of a tag in bos_name, from 1 to the number of tags. buf is the address of a character buffer that is to receive the tag name. |
| Return Value | get_tag copies the tag name into buf and returns 1 if the BOS specified by bos_name is found, and there are at least count tags attached to the BOS; otherwise, 0 is returned, and no copy is performed. |
| Comments | fetch_tag may be used to retrieve the information associated with a particular tag. |
| See Also | fetch_tag |
get_version
void get_version (
SS_VERSION *vrec )
SS_VERSION *vrec; // address of SS_VERSION struct
| Synopsis | #include
"silver.h" The get_version function retrieves version information regarding the current version of SilverScreen, and stores it into the SS_VERSION struct pointed to by vrec. |
| Parameters | vrec is the address of an SS_VERSION struct (defined in silver.h) that is to receive the version information. |
get_view
void get_view ( SS_VIEW
*v )
SS_VIEW *v; // address of view structure
| Synopsis | #include
"silver.h" The get_view function retrieves information about the current view and stores it into the SS_VIEW structure at v. |
||||||||||||||||||||||||||
| Parameters | v is the address of
an SS_VIEW struct (defined in silver.h) that is to receive the view
information. Here is an overview of the information stored in the SS_VIEW structure:
In a parallel projection, center and angle_of_view are not defined. |
getcwd
char *getcwd ( char
*buf, int length )
char *buf; // character buffer to receive directory name
int length; // size of buffer
| Synopsis | #include
"silver.h" The getcwd function retrieves the current working directory, and stores it into the character array pointed to by buf. If buf is NULL, then length bytes of storage are allocated by malloc, and the current directory is copied there. |
| Parameters | buf is either a pointer to a character buffer, or NULL. If buf is non-NULL, then it should be at least length bytes in length. |
| Return Value | getcwd returns buf, if buf was non-NULL; otherwise, the address of the allocated storage is returned. If an error occurs, NULL is returned, and errno is set to ENOMEM if buf was passed as NULL, but length bytes could not be allocated, or ERANGE if the current working directory as longer than length bytes. |
icon
int icon ( char
*title,char *name,int rows,int cols,int permissible_keys )
char *title; // text for title
char *name; // icon drawing name
int rows; // number of icon rows
int cols; // number of icon columns
int permissible_keys; // permissible return keys
| Synopsis | #include
"silver.h" The icon function loads the drawing specified by name and displays it in the icon area with the title as a heading (provided that title is not an empty string). This area is divided up into a grid of rows by cols, and each grid cell is numbered from 1, top to bottom and left to right. The drawing is expected to have a group of entities at root (blocks or objects) with names "icon1", "icon2" ... "icon<n>". The icons are matched up with a grid cell according to their numbers. An icon cell is highlighted either by mouse movements or by the keyboard arrow keys, and is selected either by the left mouse button or via carriage return. |
||||||||
| Parameters | name is name of the
drawing in which the icons are stored. rows and cols specify the number of
rows and columns in the icon area. title, if not an empty string, specifies the
heading to appear at the top of the icons. permissible_keys determines which keyboard or mouse events will be returned by the function. The keys are broken into three categories, each associated with a definition:
These definitions can be or’ed together to specify various combinations of keys. 0 specifies that no keyboard or mouse events will be returned by the function. The cells are numbered from 1, starting in the leftmost cell of startrow as before. |
||||||||
| Return Value | If an icon has been selected, the function returns the icon number of that icon. Otherwise the function returns 0. If a permissible key is pressed, 0 will be returned and the key event will be in the predefined variable ich. | ||||||||
| See Also | clear_icons, display_icon, icon2, panel_icon, panel_icon2 |
icon_persist
int icon_persist ( char
*title, char *d_name, int rows, int cols );
char *title; // title of icon bar
char *d_name; // icon drawing
int rows; // number of rows
int cols; // number of columns
| Synopsis | #include
"silver.h" The icon_persist function loads the drawing specified by name and displays it in the icon area with the title as a heading (provided that title is not an empty string). This area is divided up into a grid of rows by cols, and each grid cell is numbered from 1, top to bottom and left to right. The drawing is expected to have a group of entities at root (blocks or objects) with names "icon1", "icon2" ... "icon<n>". The icons are matched up with a grid cell according to their numbers. An icon cell is selected by clicking on it with the left mouse button. The icon bar may be docked or undocked to either the left or right edge of the SilverScreen window; its operation is otherwise unchanged. The cells are numbered from 1, starting in the leftmost cell of startrow as before. |
| Parameters | name is name of the drawing in which the icons are stored. rows and cols specify the number of rows and columns in the icon area. title, if not an empty string, specifies the heading to appear at the top of the icons. |
| Return Value | If the icon drawing was loaded successfully, then icon_persist returns 1, and 0 otherwise. |
| See Also | icon, icon2, icon2_persist |
icon_remove
void icon_remove ( void
);
| Synopsis | #include
"silver.h" The icon_remove function removes the icon bar from the screen. If the icon bar is docked, then it will cause the SilverScreen client area to resize itself. |
| Comments | Note that the related function clear_icons only clears the icon bar, but does not remove it. |
| See Also | icon, icon2, icon_persist, icon2_persist, clear_icons |
icon2
int icon2 (char *title,
char *d_name, long mask,
int rows, int cols, int
permissible_keys)
char *title; // text for title
char *d_name; // icon drawing name
int mask; // bit-mask that selects the icons
int rows; // number of icon rows
int cols; // number of icon columns
int permissible_keys; // permissible return keys
| Synopsis | #include
"silver.h" ThThe icon2 function is identical to icon, except that the mask parameter allows selective masking of icons to be displayed (that is, if bit ith of mask is 1, then the entity "icon<i>" are displayed from the icon drawing). |
| Parameters | d_name is the name of the drawing in which the icons are stored. mask selects which icons are to be displayed: if bit 3 of mask is 1, then the entity "icon3" from drawing d_name will be used. rows and cols specify the number of rows and columns in the icon area. title, if not an empty string, specifies the heading to appear at the top of the icons. |
| Return Value | Note that the return value is unaffected by mask (that is, if a selection is made, the number returned is i if the entity "icon<i>" is selected).If a selection is made, then icon returns the icon number of the highlighted icon. If Esc is pressed the icon returns 0, and the predefined variable ich is set to the terminating keystroke. If a permissible key is pressed, 0 is returned and ich is set to this key.The displayed icons are not cleared from the screen (see clear_icons). |
| See Also | clear_icons, display_icon, icon, panel_icon, panel_icon2 |
icon2_persist
int icon2_persist ( char
*title, char *d_name, int mask, int rows, int cols);
char *title; // title of icon bar
char *d_name; // icon drawing
int mask; // mask to select icons
int rows; // number of rows
int cols; // number of columns
| Synopsis | #include
"silver.h" The icon2_persist function is identical to icon_persist, except that the mask parameter allows selective masking of icons to be displayed (that is, if the ith bit of mask is 1, then the entity "icon<i>" is displayed from the icon drawing). |
| Parameters | d_name is the name of the drawing in which the icons are stored. mask selects which icons are to be displayed: if bit 3 of mask is 1, then the entity "icon3" from drawing d_name will be used. rows and cols specify the number of rows and columns in the icon area. title, if not an empty string, specifies the heading to appear at the top of the icons. |
| Return Value | If the icon drawing was loaded successfully, then icon_persist returns 1, and 0 otherwise. Note that the return value is unaffected by mask (that is, if a selection is made, the number returned is i if the entity "icon<i>" is selected). |
| See Also | icon, icon2, icon_persist |
inchar
int inchar ( void )
| Synopsis | #include
"silver.h" The inchar function returns keyboard and mouse events. If no such events are pending, inchar waits until one occurs. |
| Return Value | inchar returns the input event. A full set of inchar return events is included in the sskeys.h include file. |
| See Also | nextkey, pointer_mode, ich |
interference
int interference (
BOS_NODE *bos1, BOS_NODE *bos2 )
BOS_NODE *bos1; // address of SilverScreen block, object or symbol
BOS_NODE *bos2; // address of SilverScreen block, object or symbol
| Synopsis | #include
"ssnodes.h" The interference function checks the two blocks, objects, or symbols pointed at by bos1 and bos2 for interference, i.e. 3D overlapping. |
| Parameters | bos1 and bos2 are pointers to SilverScreen BOS's, as obtained via get_bos. |
| Return Value | interference returns 0 is if the entities do not interfere; 1 is returned if they interfere, and -1 is returned if there was a failure. |
intersect
int intersect ( SS_XYZ
*r, SS_XYZ *p1, SS_XYZ *p2, SS_XYZ *q1, SS_XYZ *q2 )
SS_XYZ *r; // address of 3D point to receive result
SS_XYZ *p1; // startpoint of first line
SS_XYZ *p2; // endpoint of first line
SS_XYZ *q1; // startpoint of second line
SS_XYZ *q2; // endpoint of second line
| Synopsis | #include
"silver.h" The intersect function computes the intersection point of the lines defined by the two line segments p1-p2 and q1-q2 and places the result in r. |
| Parameters | r, p1, p2, q1 and q2 are all addresses of 3D points. |
| Return Value | If the two lines do not intersect, then intersect returns 0, and r is unmodified; if they do intersect, then intersect returns 2 if the intersection point lies on both of the segments p1-p2 and q1-q2, and 1 otherwise (the intersection point lies on an extension of the segments). |
| See Also | intersect_3_plane, intersect_line_plane |
intersect_3_plane
int intersect_3_plane (
SS_COEF *plane1, SS_COEF *plane2, SS_COEF *plane3, SS_XYZ *xyz )
SS_COEF *plane1; // address of 1st plane structure
SS_COEF *plane2; // address of 2nd plane structure
SS_COEF *plane3; // address of 3rd plane structure
SS_XYZ *xyz; // address of intersection point
| Synopsis | #include
"silver.h" The intersect_3_plane function computes the intersection point of the three planes plane1, plane2 and plane3 and returns it in xyz. |
| Parameters | plane1, plane2 and plane3 are all addresses of planes, represented by SS_COEF structures (as defined in silver.h). xyz is the address of the the 3D point that is to receive the intersection result. |
| Return Value | If the intersection is not a point (i.e. two or more planes are parallel or coincident), or if one or more planes are degenerate, then intersect_3_plane returns 0, and xyz is not modified; otherwise intersect_3_plane returns 1. |
| See Also | intersect, intersect_line_plane |
intersect_line_plane
int intersect_line_plane
( SS_XYZ *p1, SS_XYZ *p2, SS_XYZ *r, SS_COEF *coef )
SS_XYZ *p1; // startpoint of line
SS_XYZ *p2; // endpoint of line
SS_XYZ *r; // address of 3D point to receive result
SS_COEF *coef; // address of plane structure
| Synopsis | #include
"silver.h" The intersect_line_plane function determines if the line through p1 and p2 intersects the plane specified by coef. |
| Parameters | p1, p2 and r are all addresses of 3D points. coef is the address of a plane, represented by an SS_COEF structure (as defined in silver.h). |
| Return Value | intersect_line_plane returns 0 if a line through p1 and p2 does not intersect the plane defined by coef; otherwise intersect_line_plane returns 1, and r is set to the point of intersection of the line and plane. |
| See Also | intersect, intersect_3_plane |
is_entity
int is_entity ( char
*path )
char *path; // entity name
| Synopsis | #include
"silver.h" The is_entity function checks the current SilverScreen drawing database for the existence of the entity specified by path. |
||||||||||||||
| Parameters | path is a null-terminated string containing the name of the entity. | ||||||||||||||
| Return Value | is_entity returns one
of:
|
jump_menu
int jump_menu ( void )
| Synopsis | #include
"silver.h" The jump_menu function displays the Jump menu and permits the user to select one of the jump options available on that menu. If a successful jump operations is made, then 1 is teturned; otherwise 0. |
| Return Value | jump_menu returns 1 if a successful jump operation is made; and otherwise 0. |
language_now
void language_now ( char
*buf )
char *buf; // character buffer to receive current language
| Synopsis | #include
"silver.h" The language_now function copies the current language name into buf. |
| Parameters | buf is the address of a character buffer that is to receive the current language. |
| See Also | translate_keyword |
load_ss_attribute
int
load_ss_attribute ( int bits, char *bos_name,
char *s_name, char *a_name,
SS_ATTRIBUTE *sattrib )
int bits; // entity type
char *bos_name; // entity name
char *s_name; // schema name
char *a_name; // attribute name
SS_ATTRIBUTE *sattrib; // address of attribute structure
| Synopsis | #include
"silver.h" The load_ss_attribute function retrieves the value of an attribute associated with a particular block, object or symbol. bos_name specifies the name of the entity, and bits specifies the entity type (bits must have a value of E_BLOCK, E_OBJECT or E_SYMBOL). A schema with name s_name must be attached to bos_name and contain an attribute with name a_name. The SS_ATTRIBUTE record is set to the attribute value, with its bits field is set to an appropriate value. If the requested attribute is numeric, then attr->value is assigned the value and attr->bits is set to A_NUMBER; if the requested attribute is text, then a buffer of appropriate length is allocated, attr->text is set to point at the buffer, and attr->bits is set to A_TEXT. If the attribute is fixed, then A_FIXED is or ed into the value of attr->bits. |
||||||||||||||||||
| Parameters | bits is one of E_BLOCK, E_OBJECT or E_SYMBOL. bos_name, s_name and a_name are all null-terminated strings containing the names of the entity, schema and attribute, respectively. sattrib is address of the attribute structure that is to receive the attribute data. | ||||||||||||||||||
| Return Value | load_ss_attribute
returns one of the following:
|
load_ss_variable
int load_ss_variable (
char *name, SS_VARIABLE *var )
char *name; // name of a SilverScreen variable
SS_VARIABLE *var; // address of variable structure
| Synopsis | #include
"silver.h" The load_ss_variable function attempts to load the value of the specified SilverScreen system variable into the SS_VARIABLE record pointed to by var. |
||||||||||||
| Parameters | name is a null-terminated string containing the name of a SilverScreen variable (including the leading '$'). var is the address of an SS_VARIABLE structure, as defined in silver.h. | ||||||||||||
| Return Value | load_ss_variable
returns one of the following:
|
||||||||||||
| Comments | For text variables, the memory to hold the text string is allocated via malloc, and assigned to the text field of the var parameter. free should be called to deallocate the memory used by the text string when you are finished using it. | ||||||||||||
| Example | Assume that $tvar is
the name of a SilverScreen system text variable:
|
locate
void locate ( int x, int
y )
int x; // screen column
int y; // screen line
| Synopsis | #include
"silver.h" The locate function positions the text cursor on the screen at character positions x and y. The text cursor determines the location of the next output to stdout. |
| Parameters | x and y are integers denoting the cursor position, with 0 < y < schar_height, and 0 < x < schar_width. |
| Comments | This function is currently obsolete. |
| See Also | printf, vprintf, text_mode_locate |
make_path
void make_path ( void
*bos, char *path )
void *bos; // pointer to block, object or symbol node
char *path; // character buffer to receive path
| Synopsis | #include
"ssnodes.h" The make_path function stores the path of the BOS node bos into path. |
| Parameters | bos is a direct pointer to a entity node as obtained by get_bos, cast to a void pointer. p is the address of a character buffer that is to receive the path. |
| See Also | get_bos |
mark_area
int mark_area ( char *message,
double *x1, double *y1,
double *x2, double *y2 )
char *message; // prompt message
double *x1; // address of normalized left coordinate
double *y1; // address of normalized upper coordinate
double *x2; // address of normalized right coordinate
double *y2; // address of normalized lower coordinate
| Synopsis | #include
"silver.h" The mark_area function displays message, and then allows the user to select a rectangular area from the current screen. The coordinates pairs (x1 ,y1) and (x2 ,y2) specify the corners of the rectangular area as measured in normalized coordinates relative to the current screen; that is (0,0) is the lower left corner of the screen, (0,1) is the upper left corner, (1,0) is the lower right corner and (1,1) is the upper right corner of the screen. |
| Parameters | message is a null-terminated string containing the prompt message. x1, x2, y1 and x2 are all addresses of doubles that are to receive the normalized area coordinates. |
| Return Value | If the selection is successfully made, the coordinates of the area are stored into the doubles at x1, y1, x2 and y2, and mark_area returns 1; otherwise, mark_area returns 0. |
| Example | The following example uses mark_area
to zoom the current window: double d1,d2,d3,d4; |
menu
int menu ( char
*menu_name )
char *menu_name; // string containing menu name
| Synopsis | #include
"silver.h" The menu function causes the specified custom menu to be loaded, and allows the user to make a menu selection from it. |
| Parameters | menu_name is a null-terminated string containing the base name of the menu to be loaded, which will be appended with ".CMF", to form the file name. |
| Return Value | menu returns the number associated with the menu item if a selection was successfully made. Otherwise, if Esc was pressed, menu returns 0. If a control key or function key was pressed, the predefined variable ich is set to the value of the key pressed, and menu returns 1. |
menu_check_item
int menu_check_item (
int item, int setting )
int item; // menu item number
int setting; // new check setting
| Synopsis | #include
"silver.h" The menu_check_item function causes the specified custom menu item to be checked or unchecked, based on the value of setting. |
| Parameters | item is the item number for a leaf of a custom menu which identifies the menu item. setting is the setting: 0 to uncheck the item, or any other value will check it. |
| Return Value | menu_check_item returns the previous check setting for the item. |
| Comments | menu_check_item operates on all of the menu items with number item. The value returned is that of the last menu item with that number. An item that is checked is displayed with a small check beside it. |
| See Also | menu, menu_persist, menu_unload, menu_enable_item |
menu_enable_item
int menu_enable_item (
int item, int setting )
int item; // menu item number
int setting; // new enable setting
| Synopsis | #include
"silver.h" The menu_enable_item function causes the specified custom menu item to be enabled, disabled or grayed, based on the value of setting. |
| Parameters | item is the item number for a leaf of a custom menu which identifies the menu item. setting is the setting: 0 to disable the item; 2 to gray it. Any other value will enable it. |
| Return Value | menu_enable_item returns the previous enable setting for the item. |
| Comments | menu_enable_item operates on all of the menu items with number item. The value returned is that of the last menu item with that number. An item that is grayed is displayed in a light gray, and may not be selected, whereas an item that is disabled is displayed as normal, but may not be selected. |
| See Also | menu, menu_persist, menu_unload, menu_check_item |
menu_persist
int menu_persist ( char
*menu_name );
char *menu_name;
| Synopsis | #include
"silver.h" The menu_persist function loads a custom menu into the Windows menu area. |
| Parameters | menu_name is a character string that specifies the name of the custom menu to load. Identical to that used in menu. |
| Return Value | menu_persist returns 1 if the menu was loaded properly, and 0 otherwise (most likely memory for the menu could not be allocated, or the menu anme is somehow invalid). |
| Comments | menu_persist
differs from menu in that menu is used to make one selection from a custom
menu, which is then removed; while menu_persist loads a menu and leaves it
in place as events are retrieved via inchar. A menu selection is signified when inchar
returns CM_EVENT; the selection may then be obtained by a call to get_event_info. If the menu that is replaced by menu_persist is a custom menu, then it is discarded; otherwise, it is saved on a stack, and then restored when the custom menu is discarded via a call to menu_unload. |
| See Also | menu, menu_unload, get_event_info |
menu_unload
void menu_unload ( void
);
| Synopsis | #include
"silver.h" The menu_unload function removes the currently loaded custom menu from the menu area, and restores the previous menu. |
| See Also | menu_persist |
message_area_configure
void
message_area_configure ( int lines, int bg_color);
int lines; // number of lines to allocate
int bg_color; // background color of message area
| Synopsis | #include
"silver.h" The message_area_configure function allocates a number of lines from the SilverScreen view window that may be written to by using the message_area_write function. The lines allocated are subtracted from the top of the current view window. |
| Parameters | lines is an integer value specifying the number of lines to allocate; if it is 0, then the message area will be closed. bg_color is the color used for the background of the message area, and should be in the range of [0, num_colors - 1]. |
| Comments | This function will cause a resize of the SilverScreen view window. For developers who operate in "redraw local" mode (as if by cv_set ( REDRAW_LOCAL, 1 )), this resize event will need to be handled. |
| See Also | message_area_write |
message_area_write
void message_area_write
( char *text, int line, int color );
char *text; // character string to display
int line; // line number to display text
int fg_color; // foreground color for text
| Synopsis | #include
"silver.h" The message_area_write function writes the specified text string in the message area. |
| Parameters | text is the message string to be displayed. line is an integer specifying the line in the message area to display the text string, where 1 is the first line, and so on. fg_color is the color used to render the text, and should be in the range [0, num_colors - 1]. |
| Comments | message_area_configure must be called to allocate the message area before calling message_area_write. |
| See Also | message_area_configure |
mkdir
int mkdir ( char
*dirname )
char *dirname; // new directory name
| Synopsis | #include
"silver.h" The mkdir function creates a new directory with the specified dirname. Only one directory may be created at a time, so if the dirname contains path component, all but the last one must already exist. |
| Parameters | dirname is a null-terminated string containing the new directory name. |
| Return Value | mkdir returns 0 if successful; and otherwise EOF (-1). |
| See Also | rmdir, chdir |
nextkey
int nextkey ( void )
| Synopsis | #include
"silver.h" The nextkey function examines the input event queue for a keyboard or mouse event. |
| Return Value | If there is an event in the queue, nextkey returns it, without removing it from the queue; if there is no event in the queue, nextkey returns 0. |
| See Also | inchar |
p_to_w
int p_to_w ( SS_XYZ *pt,
int screen_x, int screen_y )
SS_XYZ *pt; // address of 3D point to receive world point
int screen_x; // screen x coordinate
int screen_y; // screen y coordinate
| Synopsis | #include
"silver.h" The p_to_w function computes a 3D world coordinate based on the screen coordinates screen_x and screen_y. The world point is copied into the SS_XYZ at pt. |
| Parameters | pt is the address of a 3D point that is to receive the computed world point. screen_x and screen_y are graphics screen coordinates, such that 0 <= screen_x < spixel_width and 0 <= screen_y < spixel_height. |
| Return Value | If the screen coordinate is within the bounds of the current window, then p_to_w returns 1, and pt is computed such that it lies on the current window in world space. Otherwise p_to_w returns 0. |
| Comments | While related to the function w_to_p, the two are not inverse functions. Calling p_to_w with the results of w_to_p may not return the original point because w_to_p does not preserve any depth information, and may truncate a value when converting to integer space. |
| See Also | w_to_p |
paint_begin
void paint_begin ( void
);
| Synopsis | #include
"silver.h" The paint_begin function disables drawing to the screen during window repaints. Drawing to the refresh buffer still occurs. |
| Comments | paint_begin should be followed by a call to paint_end after finishing a drawing operation. The contents of the refresh buffer will be copied to the screen. Calls to paint_begin and paint_end should not be nested, although intervening calls to paint_flush may take place at any time. |
| See Also | paint_end, paint_flush |
paint_end
void paint_end ( RECT
*rect );
| Synopsis | #include
"silver.h" The paint_end function re-enables drawing to both the screen and the refresh bitmap, and then updates the window rectangle referred to by rect from the refresh buffer. |
| Parameters | rect is a pointer to a RECT that defines an area of the SilverScreen view window which is to be updated from the refresh buffer. |
| Comments | paint_end should only follow a previous call to paint_begin. Calls to paint_begin and paint_end should not be nested, although intervening calls to paint_flush may take place at any time. |
| See Also | paint_begin, paint_flush |
paint_entity
int paint_entity ( char
*path, int color )
char *path; // path name of block, object or symbol
int color; // color to use
| Synopsis | #include "silver.h"The paint_entity function draws the specified entity in the specified color. | ||||||||||||
| Parameters | path is the full path name of the entity. color is the color used to draw the entity. | ||||||||||||
| Return Value | paint_entity returns SS_SUCCESS (0) if the spcified block, object or symbol exists, and SS_NOTFOUND (-1) otherwise. | ||||||||||||
| Comments | The maximum number of colors
in the system is given by the system variable num_colors. The current maximum for num_colors
is 256, and therefore the lower byte only is used for color information. The color parameter may have the following
flags or'ed into its value:
|
||||||||||||
| See Also | paint_entity_rgb, paint_primitive, paint_primitive_rgb |
paint_entity_rgb
int paint_entity ( char
*path, RGB rgb, int mode )
char *path; // path name of block, object or symbol
RGB rgb; // rgb color to use
int mode; // parameters for painting
| Synopsis | #include
"silver.h" The paint_entity_rgb function draws the specified entity in the specified rgb color. |
|||||||||
| Parameters | path is the full path name of the entity. rgb is the color used to draw the entity. | |||||||||
| Return Value | paint_entity returns SS_SUCCESS (0) if the specified entity exists, and SS_NOTFOUND (-1) otherwise. | |||||||||
| Comments | The mode parameter
may have the following or’ed values:
|
|||||||||
| See Also | paint_entity, paint_primitive,paint_primitive_rgb |
paint_flush
void paint_flush ( RECT
*rect );
| Synopsis | #include
"silver.h" The paint_flush function updates the window rectangle referred to by rect from the refresh buffer. |
| Parameters | rect is a pointer to a RECT that defines an area of the SilverScreen view window which is to be updated from the refresh buffer. |
| Comments | Calls to paint_flush may take place at any time, although they are usually most appropriate between calls to paint_begin and paint_end, to give the user some feedback as to screen activity. |
| See Also | paint_begin, paint_end |
paint_primitive
int paint_primitive (
char *path, int id, int color )
char *path; // path to object containing primitive
int id; // ID number of primitive
int color; // color to use
| Synopsis | #include "silver.h"The paint_primitive function draws the specified primitive in the specified color. The primitive is designated by path, which is the name of the object that contains the primitive, and id, which is the ID number of the primitive primitive. | ||||||||||||
| Parameters | path is a
null-terminated string containing the full path name of the object containing the
primitive. id is the ID number of the primitive in the object at path. color
is the color used to draw the primitive. The color parameter may have the following flags or'ed into its value:
|
||||||||||||
| Return Value | paint_primitive returns SS_SUCCESS (0) if the specified primitive exists, and SS_NOTFOUND (-1) otherwise. | ||||||||||||
| Comments | See the comment for paint_entity for a description of permissible color values. | ||||||||||||
| See Also | paint_primitive_rgb, paint_entity, paint_entity_rgb |
paint_primitive_rgb
int paint_primitive_rgb
( char *path, int id, RGB rgb, int mode )
char *path; // path to object containing primitive
int id; // ID number of primitive
RGB rgb; // rgb color to use
int mode; // parameters for painting
| Synopsis | #include "silver.h"The paint_primitive_rgb function draws the specified primitive in the specified rgb. The primitive is designated by path, which is the name of the object that contains the primitive, and id, which is the ID number of the primitive primitive. | |||||||||
| Parameters | path is a
null-terminated string containing the full path name of the object containing the
primitive. id is the ID number of the primitive in the object at path. rgb
is the rgb color used to draw the primitive. Mode may have the following or’ed
values:
|
|||||||||
| Return Value | paint_primitive_rgb returns SS_SUCCESS (0) if the spcified primitive exists, and SS_NOTFOUND (-1) otherwise. | |||||||||
| See Also | paint_primitive, paint_entity, paint_entity_rgb |
panel_empty
void panel_empty ( int
top, int left, int bottom, int right, int color )
int top; // top of panel
int left; // left side of panel
int bottom; // bottom of panel
int right; // right side of panel
int color; // border color
| Synopsis | #include
"silver.h" The panel_empty function displays an empty raised panel in the area specified by the character locations: top, left, bottom and right. The border color of the raised panel is specified by color. |
| Parameters | top, left, bottom and right are all character locations on the screen, with 1 <= top <= bottom <= schar_height, and 1 <= left <= right <= schar_width. color is a color number. |
panel_icon
int panel_icon ( char *title,
char *d_name, int rows, int cols,
double how_high, double how_wide )
char *title; // title string
char *d_name; // icon drawing name
int rows; // number of icon rows
int cols; // number of icon columns
double how_high; // normalized height of icons
double how_wide; // normalized width of icons
| Synopsis | #include
"silver.h" The panel_icon function is similar to icon except that the icons are displayed within a panel rather than within the menu area. title is the title line that appears at the top of the panel. d_name specifies the name of the drawing in which icons are stored. how_high and how_wide are used to give the height and width of individual icons relative to the height and width of the screen. A height of 0.1, for example, specifies that the height of a single icon is to be one-tenth of the height of the screen. |
| Parameters | title is a null-terminated string containing the panel title. d_name is a null-terminated string containing the name of the drawing in which the icons are stored. rows and cols are integers specifiying the number of icon rows and columns in the panel. how_high and how_wide are normalized doubles (between 0 and 1) specifying the height and width of icons relative to screen height and width. |
| Return Value | If a selection is made, panel_icon returns the icon number of the selected icon. Otherwise 0 is returned. |
| See Also | icon, icon2 |
panel_icon2
int panel_icon2 ( char *title,
char *d_name, long who, int rows, int cols,
double how_high, double how_wide )
char *title; // title string
char *d_name; // icon drawing name
long who; // bit-mask for selecting icons
int rows; // number of icon rows
int cols; // number of icon columns
double how_high; // normalized height of icons
double how_wide; // normalized width of icons
| Synopsis | #include
"silver.h" The panel_icon2 function identical to panel_icon except that the mask parameter who allows selective masking of icons to be displayed. If the ith bit of who is 1, then "icon<i>" is displayed. The return values are unaffected by who; the function returns i if "icon<i>" is selected. |
| Parameters | title is a null-terminated string containing the panel title. d_name is a null-terminated string containing the name of the drawing in which the icons are stored. who is a bit mask specifying which icons are to be used. rows and cols are integers specifiying the number of icon rows and columns in the panel. how_high and how_wide are normalized doubles (between 0 and 1) specifying the height and width of icons relative to screen height and width. |
| Return Value | panel_icon2 returns the same values as panel_icon: if a selection is made, then panel_icon2 returns the icon number of the selected icon. Otherwise 0 is returned. |
| See Also | panel_icon, icon |
panel_input
int panel_input ( char
*message, char *buf )
char *message; // prompting message
char *buf; // address of character buffer to receive input string
| Synopsis | #include
"silver.h" The panel_input function displays a panel in the center of the screen and a prompting message specified by message, and then accepts a string of characters from an input area within the panel. |
| Parameters | message is a null-terminated string containing the prompt message. buf is a character array that is to receive the input string. |
| Return Value | If the input process terminates with Esc, then panel_input returns 0; otherwise panel_input copies the input string into buf, and returns 1. |
panel_message
void panel_message (
char *message )
char *message; // message string
| Synopsis | #include
"silver.h" The panel_message function displays a message at the center of the screen inside a panel. The messages may extend over several lines. Individual lines of the message are delimited by the vertical bar, for example: "First line|Second line|Third line". The message disappears when a key or a button is pressed. |
| Parameters | message is a null-terminated string containing the message lines. |
| Example | panel_message ("First line|Second line|Third line"); |
path_drawing
void path_drawing ( char
*buf )
char *buf; // character buffer to receive directory name
| Synopsis | #include
"silver.h" The path_drawing function copies the name of the current drawing directory into buf. The directory name is always terminated by a backslash ('\') character. |
| Parameters | buf is the address of a character buffer that is to receive the directory name. |
path_execution
void path_execution (
char *buf )
char *buf; // character buffer to receive directory name
| Synopsis | #include "silver.h" The path_execution function copies the name of the current SilverScreen execution directory into buf. |
| Parameters | buf is the address of a character buffer that is to receive the directory name. |
| Comments | The directory name is always terminated by a backslash ('\') character. |
path_home
void path_home ( char
*buf )
char *buf; // character buffer to receive directory name
| Synopsis | #include
"silver.h" The path_home function copies the name of the current SilverScreen home directory into buf. |
| Parameters | buf is the address of a character buffer that is to receive the directory name. |
| Comments | The directory name is always terminated by a backslash ('\') character. |
path_library
void path_library ( char
*buf )
char *buf; // character buffer to receive directory name
| Synopsis | #include
"silver.h" The path_library function copies the name of the current SilverScreen library directory into buf. |
| Parameters | buf is the address of a character buffer that is to receive the directory name. |
| Comments | The directory name is always terminated by a backslash ('\') character. |
path_silver
void path_silver ( char
*buf )
char *buf; // character buffer to receive directory name
| Synopsis | #include
"silver.h" The path_silver function copies the name of the current SilverScreen directory into buf. |
| Parameters | buf is the address of a character buffer that is to receive the directory name. |
| Comments | The directory name is always terminated by a backslash ('\') character. |
path_temp
void path_temp ( char
*buf )
char *buf; // character buffer to receive directory name
| Synopsis | #include
"silver.h" The path_temp function copies the name of the current SilverScreen temporary directory into buf. |
| Parameters | buf is the address of a character buffer that is to receive the directory name. |
| Comments | The directory name is always terminated by a backslash ('\') character. |
pick_entity
int pick_entity ( char
*message, int e_type, char *buf )
char *message; // prompt message
int e_type; // entity type mask
char *buf; // character buffer to receive entity name
| Synopsis | #include
"silver.h" The pick_entity function displays message and then allows the user to pick an entity, based on e_type. |
| Parameters | message is a null-terminated string containing the prompt message. e_type is an integer value specifying which entity types are to be considered for picking: E_BLOCK, E_DETAIL, E_OBJECT, E_SYMBOL, or E_TEXT may be or'ed together to obtain e_type. buf is a character buffer that is to receive the full path name of the selected entity. |
| Return Value | If a selection is successfully made, then 1 is returned and the path name of the selected entity is copied into buf; otherwise, 0 is returned. |
| Comments | pick_entity operates in pick mode. The function prompt_entity operates in either pick or scan mode, while scan_entity operates in scan mode. |
| See Also | prompt_entity, scan_entity |
pick_primitive
int pick_primitive (
char *message, int p_type, char *buf )
char *message; // prompt message
int p_type; // primitive type mask
char *buf; // character buffer to receive primitive name
| Synopsis | #include
"silver.h" The pick_primitive function displays message and then allows the user to pick a primitive, based on p_type. |
| Parameters | message is a null-terminated string containing the prompt message. p_type is an integer value specifying which primitive types are to be considered for picking: P_ARC, P_BEZIER, P_CIRCLE, P_LINE, P_POLYGON, P_POLYLINE or P_SPLINE may be or'ed together to obtain p_type. buf is a character buffer that is to receive the full path name of the selected primitive. |
| Return Value | If a selection is successfully made, then 1 is returned and the path name of the selected primitive is copied into buf; otherwise, 0 is returned. |
| Comments | If p_type is P_LINE
or P_ARC, then pick_primitive selects only independent lines or arcs. That
is, it does not select lines or arcs that are contained in polygons or polylines. In order
to select lines and arcs that are contained within polygons or polylines, P_LINE or
P_ARC must be combined with P_POLYGON and/or P_POLYLINE. pick_primitive operates in pick mode. The function prompt_primitive operates in either pick or scan mode, while scan_primitive operates in scan mode. |
| See Also | prompt_primitive, scan_primitive |
| Example | char buf[200]; pick_primitive("Select",P_POLYGON|P_LINE, buf); pick_primitive("Select",P_POLYLINE|P_PLINE|P_ARC,buf); pick_primitive("Select",P_POLYLINE|P_POLYGON|P_ARC, buf); The first call selects a line from the set of lines contained in polygons. The second call selects a line or an arc from those lines and arcs contained in polylines. The third call selects an arc from those arcs contained in either a polygon or a polyline. |
pixel_clear
void pixel_clear ( int x1,
int y1, int x2, int y2, int color )
int x1; // left edge of pixel area
int y1; // right edge of pixel area
int x2; // top edge of pixel area
int y2; // bottom edge of pixel area
int color; // color to use
| Synopsis | #include
"silver.h" The pixel_clear function clears the area specified with pixel coordinates x1, x2, y1, and y2 to the color specified by color. |
| Parameters | x1, y1, x2 and y2 are pixel coordinates, with 0 <= x1, x2 < spixel_width and 0 <= y1, y2 < spixel_height. color is a color number. |
| See Also | clear_area |
pixel_in_primitive
int pixel_in_primitive (
PRIM_NODE *prim, int x, int y )
PRIM_NODE *prim; // pointer to primitive
int x; // x coordinate of pixel
int y; // y coordinate of pixel
| Synopsis | #include
"silver.h" The pixel_in_primitive function function examines primitive prim to determine if the pixel a location x, y lies within the boundaries of the primitive. |
| Parameters | prim is a pointer to a primitive. x and y are pixel coordinates, with 0 <= x < spixel_width and 0 <= y < spixel_height. |
| Return Value | If the pixel lies within the boundary of the primitive, 1 is returned. Otherwise 0 is returned. |
pm_box
void pm_box ( char
*message, char *menu, char *buf )
char *message; // prompt string
char *menu; // menu string
char *buf; // initial value
| Synopsis | #include
"silver.h" The pm_box function adds a menu to the current panel. The prompt string is specified by message. The menu parameter specifies the menu items, a list space-delimited keywords (for example, "left right top bottom"). The buf parameter specifies the default selection, which must match one of the keywords in menu. After pm_execute, buf will be set to the string in menu selected by the user. |
| Parameters | message is a null-terminated string containing the prompt message. menu is a null-terminated string containing the menu items. buf contains a null-terminated string designating the default selection, and which will receive the selected value. |
| Comments | In the panel, a menu will display only the current setting. A button will appear to the left of the item. When the user selects this item, a selection panel will appear containing all menu items in the panel. (If the menu has only two items, a toggle button will appear). |
| See Also | pm_box2, pm_execute |
| Example | strcpy( buf,
"left" ); pm_box ("Select view","right left front rear",buf); |
pm_box2
void pm_box2 ( char
*message, char *menu, int *selection )
char *message; // prompt string
char *menu; // menu string
int *selection; // address of integer to receive menu selection number
| Synopsis | #include
"silver.h" The pm_box2 function identical to pm_box except that selection specifies the item number of the default item initially selected in the menu. After pm_execute, setting will contain the number of item that was selected, from 1 to the number of items in menu. |
| Parameters | message is a null-terminated string containing the prompt message. menu is a null-terminated string containing the menu items. selection is the address of the integer that is to receive the item number corresponding to the selected menu item; it will be a value between 1 and the number of items on the menu. |
| Comments | The initial value for the field is the inial value of the integer pointed to by selection.In the panel, a menu will display only the current setting. A button will appear to the left of the item. When the user selects this item, a selection panel will appear containing all menu items in the panel. (If the menu has only two items, a toggle button will appear). |
| See Also | pm_box, pm_execute |
| Example | i = 2; pm_box2("Select view","right left front rear",&i ); |
pm_color
void pm_color ( char
*message, int *color )
char *message; // prompt string
RGB *color; // address of RGB to receive result
| Synopsis | #include
"silver.h" The pm_color function adds a color prompt to the current panel, with prompt specified by message. The color prompt is initialized with the RGB pointed to by color. After pm_execute, the resulting color value is returned in color. |
| Parameters | message is a null-terminated string containing the prompt message. color is the address of an RGB structure. |
| Comments | The initial value for the field is the inial value of the RGB pointed to by color. |
| See Also | pm_execute |
| Example | c = 15; pm_color ( "Edge color", &c ); |
pm_comment
void pm_comment ( char
*message )
char *message; // comment string
| Synopsis | #include "silver.h" The pm_comment function adds a comment line to the current panel. |
| Parameters | message is a null-terminated string containing the comment line. |
| See Also | pm_execute |
pm_displacement
void pm_displacement (
char *message, SS_XYZ *pt, int use_c_space )
char *message; // prompt string
SS_XYZ *pt; // address of 3D point to receive displacement
int use_c_space; // space flag
| Synopsis | #include
"silver.h" The pm_displacement function adds a displacement prompt to the current panel, with prompt specified by message. When the panel is displayed, the user will have the option of marking a distance in the drawing. If use_c_space is 1, then the marking process will be relative to c-space; otherwise w-space will be used. |
| Parameters | message is a null-terminated string containing the prompt message. pt is the address of the 3D point that will receive the displacement value. use_c_space is an integer specifying whether to use c-space or w-space marking. |
| Comments | The initial value for the field is the inial value of the SS_XYZ pointed to by value. |
| See Also | pm_execute |
pm_distance
void pm_distance ( char
*message, double *value )
char *message; // prompt string
double *value; // address of double to receive distance result
| Synopsis | #include
"silver.h" The pm_distance function adds a distance prompt to the current panel, with prompt specified by message. When the panel is displayed, the user will have the option of marking a distance in the drawing. After pm_execute, the resulting value is returned in value. |
| Parameters | message is a null-terminated string containing the prompt message. value is the address of the double that is to receive the result of the distance prompt. |
| Comments | The initial value for the field is the inial value of the double pointed to by value. |
| See Also | pm_execute |
pm_double
void pm_double ( char
*message, double *value, int mandatory )
char *message; // prompt string
double *value; // address of double to receive result
int mandatory; // mandatory entry flag
| Synopsis | #include
"silver.h" The pm_double function adds a prompt for a double value to the current panel, with prompt specified by message. If mandatory is 1, a value must be entered for the item. If mandatory is 0, then the initial value can be accepted without change. After pm_execute, the resulting value is returned in value. |
| Parameters | message is a null-terminated string containing the prompt message. value is the address of a double that is to receive the result of the prompt. mandatory is an integer specifying whether entry for this field is mandatory or not. |
| Comments | The initial value for the field is the inial value of the double pointed to by value. |
| See Also | pm_execute |
| Example | v = 10.0; pm_double ( "Height of tool", &v, 0 ); |
pm_execute
int pm_execute ( void )
| Synopsis | #include
"silver.h" The pm_execute function displays the current panel (as initialized by pm_initialize) and permits the user to modify any values that appear in the panel. Mandatory items will be entered first. Upon return from the panel, all values that have been modified by the user will be updated. This updating will occur regardless of whether a 1 or a 0 is returned by pm_execute. |
| Return Value | If the user concludes his activities by pressing the "OK" button, then 1 is returned. If the "Cancel" button is pressed, then 0 is returned. |
| See Also | pm_initialize |
| Example | An example showing
construction and display of a panel: int orientation, color; width = 8.0; border_color = color_brown; if ( pm_execute () ) |
pm_font
void pm_font ( char
*message, char *buf )
char *message; // prompt string
char *buf; // address of buffer to receive result
| Synopsis | #include
"silver.h" The pm_font function adds a font prompt to the current panel, with prompt specified by message. buf can be initialized to an empty string, or can be initialized to a font script. After pm_execute, the resulting font script is returned in buf. |
| Parameters | message is a
null-terminated string containing the prompt message. buf should be at least 80
characters in length. The font script will specify either a TrueType font or a
SilverScreen font. Formats for these two font types are illustrated below: truetype "Arial Black" weight 400 italic disable font txt.fnt The format of the font script is designed to be used with the text property command (text insertion) and the set command (annotation). |
| See Also | pm_execute |
| Example | char buf[80]; strcpy(buf, "\"Arial Black\"
weight 400 italic disable"); |
pm_formatted
void pm_formatted ( char
*message, double *value,
int mandatory, int units, int notation )
char *message; // prompt string
double *value; // address of double to receive result
int mandatory; // mandatory entry flag
int units; // unit of measurement selector
int notation; // notation selector
| Synopsis | #include
"silver.h" The pm_formatted function adds a formatted double prompt to the current panel, with prompt specified by message. The value will be displayed on the panel according to units and notation. (see format_double) If mandatory is 1, a value must be entered for the item. If mandatory is 0, then the initial value can be accepted without change. After pm_execute, the resulting value is returned in value. |
||||||||||||||||||||||||||
| Parameters | message is a
null-terminated string containing the prompt message. value is the address of a
double that is to receive the result of the prompt. mandatory is an integer
specifying whether entry for this field is mandatory or not. notation is one of the
following values (defined in silver.h):
units may be one of the following (defined in silver.h)
|
||||||||||||||||||||||||||
| See Also | pm_execute | ||||||||||||||||||||||||||
| Example | double width =
36.0; pm_formatted("Width of door",&width,ARCHITECT,INCHES,0); |
pm_generic
void pm_generic ( char
*message, char *buf, int type, char *extra_text )
char *message; // prompt string
char *buf; // character buffer to receive data
int type; // generic item type
char *extra_text; // extra text
| Synopsis | #include "silver.h"The pm_generic function adds a generic item prompt to the current panel, with prompt specified by message. buf must be initialized to an initial string value. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Parameters | message is a
null-terminated string containing the prompt message. buf is the address of the
buffer that is to receive the result. extra_text is an auxiliary string appropriate
to type. g_type may take on the following values (as defined in silver.h):
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See Also | pm_execute; also see Panel Menus |
pm_help_file
void pm_help_file ( char
*help_file )
char *help_file; // help file name
| Synopsis | #include
"silver.h" The pm_help_file function assocates a panel with a text file containing help information. This function must be executed after pm_initialize and before pm_execute. When the panel is displayed, a help button will appear in the panel. By pressing this button, the user can display the information contained in the text file. There is no special format for the help file text. |
| Parameters | help_file is a null-terminated string containing the name of the help file. |
| Comments | Text files may be stored in
executable libraries. If the text file file3.txt is stored in the library helplib,
then the file could be accessed by: pm_help_file ( "helplib>file3.txt" ); |
| See Also | pm_execute, pm_help_line |
pm_help_line
int pm_help_line ( char
*help_line )
char *help_line; // help line string
| Synopsis | #include
"silver.h" The pm_help_line function associates a single line of help text with a panel. This function may be called repeatedly, between invocations of pm_initialize and pm_execute, to build up a body of help information. When the panel is displayed, a help button will permit the user to display the help information in a pop-up panel. |
| Parameters | help_line is a null-terminated string containing a help line. |
| See Also | pm_execute, pm_help_file |
| Example | pm_initialize (
"Panel Menu" ); pm_help_line ( "This is the first line of help" ); pm_help_line ( "This is the second line of help" ); pm_help_line ( "This is the third line of help" ); ... if ( pm_execute () ) ... |
pm_icon
void pm_icon ( char
*message, char *buf, char *title, char *d_name,
int rows, int cols, double how_high, double how_wide )
char *message; // prompt string
char *buf; // address of character buffer to receive result
char *title; // title string
char *d_name; // icon drawing name
int rows; // number of icon rows
int cols; // number of icon columns
double how_high; // normalized height of icons
double how_wide; // normalized width of icons
| Synopsis | #include
"silver.h" The pm_icon function adds an icon prompt to the current panel, with prompt specified by message. The panel will contain a button which, if pressed, will display a panel as if by use of panel_icon. The result from this panel will be one of two possibilities:
|
| Parameters | message is a null-terminated string containing the prompt message. buf is the address of a character buffer which is to receive the result. title is a null-terminated string containing the icon box title. d_name is is a null-terminated string containing the name of the drawing in which the icons are stored. rows and cols are integers specifiying the number of icon rows and columns in the panel. how_high and how_wide are normalized doubles (between 0 and 1) specifying the height and width of icons relative to screen height and width. |
| Comments | The TAG command may be used to attach tag values to SilverScreen entities. |
| See Also | pm_execute, panel_icon, pm_icon2 |
| Example
#include
"silver.h" |
|
pm_icon2
void pm_icon2 ( char
*message,char *buf,char *title, char *d_name,
int who, int rows, int cols,
double how_high, double how_wide )
char *message; // prompt string
char *buf; // address of character buffer to receive result
char *title; // title string
char *d_name; // icon drawing name
int who; // bit-mask for selecting icons
int rows; // number of icon rows
int cols; // number of icon columns
double how_high; // normalized height of icons
double how_wide; // normalized width of icons
| Synopsis | #include
"silver.h" The pm_icon2 function adds an icon prompt to the current panel, with prompt specified by message. pm_icon2 is identical to pm_icon except that mask can be used for a selective display of icons. mask is as described in panel_icon2. |
| Parameters | message is a null-terminated string containing the prompt message. buf is the address of a character buffer which is to receive the result. title is a null-terminated string containing the icon box title. d_name is is a null-terminated string containing the name of the drawing in which the icons are stored. who is a bit mask specifying which icons are to be used. rows and cols are integers specifiying the number of icon rows and columns in the panel. how_high and how_wide are normalized doubles (between 0 and 1) specifying the height and width of icons relative to screen height and width. |
| See Also | pm_execute, pm_icon, panel_icon2 |
pm_initialize
void pm_initialize (
char *title, char *dummy )
char *title; // panel title string
char *dummy; // not used at present
| Synopsis | #include
"silver.h" The pm_initialize function is the first step in the construction and display of a popup panel. After this function has been called, items are added to the panel (via pm_double, pm_menu, etc.), and finally pm_execute is called. The panel will be displayed with title at the top. The variable dummy is will be used in a future version of SilverC. In this version, an empty string ("") should be used. |
| Parameters | title is a null-terminated string containing the title to be used with the panel. dummy is a character pointer, which is not used at present, and should be the empty string ("", not NULL). |
| See Also | pm_execute |
pm_integer
void pm_integer ( char
*message, int *value, int mandatory )
char *message; // prompt string
int *value; // address of int to receive result
int mandatory; // mandatory entry flag
| Synopsis | #include
"silver.h" The pm_integer function adds a prompt for an integer value to the current panel, with prompt specified by message. If mandatory is 1, a value must be entered for the item. If mandatory is 0, then the initial value can be accepted without change. After pm_execute, the resulting value is returned in value. |
| Parameters | message is a null-terminated string containing the prompt message. value is the address of an integer that is to receive the result of the prompt. mandatory is an integer specifying whether entry for this field is mandatory or not. |
| See Also | pm_execute |
pm_line_width
void pm_line_width (
char *message, int *value )
char *message; // prompt string
int *value; // address of int to receive result
| Synopsis | #include
"silver.h" The pm_line_width function adds a prompt for a line width to the current panel, with prompt specified by message. After pm_execute, the resulting value is returned in value. |
| Parameters | message is a null-terminated string containing the prompt message. value is the address of an integer that is to receive the result of the prompt. |
pm_menu
void pm_menu ( char
*message, char *menu, int *selection )
char *message; // prompt string
char *menu; // menu string
int *selection; // address of integer to receive menu selection number
| Synopsis | #include
"silver.h" The pm_menu function adds a menu prompt to the current panel. The prompt string is specified by message. The menu parameter specifies the menu items, a list space-delimited keywords (for example, "left right top bottom"). |
| Parameters | message is a null-terminated string containing the prompt message. menu is a null-terminated string containing the menu items. selection is the address of the integer that is to receive the item number corresponding to the selected menu item; it will be a value between 1 and the number of items on the menu. After pm_execute, setting will contain the number of item that was selected, from 1 to number of keywords. |
| Comments | The initial value for the
field is the inial value of the integer pointed to by selection. pm_menu differs from pm_box2 in that the menu is always displayed in pm_menu, as opposed to pm_box2, where the menu only appears if the user attempts to edit the field. |
| See Also | pm_execute, pm_box2 |
| Example | item_number = 1; pm_menu ("Select view", "Front Rear Left Right",&item_number); |
pm_rgb
void pm_rgb ( char
*message, char *buf )
char *message; // prompt string
char *buf; // character buffer to receive RGB string
| Synopsis | #include
"silver.h" The pm_rgb function adds a prompt for an RGB string to the current panel, with prompt specified by message. When the panel is displayed, a button will permit the user to use any of the color selection facilities to select a color. After pm_execute, buf will contain the resulting string. If properly formatted, the string can be converted to RGB values (see text_to_rgb). |
| Parameters | message is a null-terminated string containing the prompt message. buf is the address of a character buffer that is to receive the character string. |
| See Also | pm_execute, text_to_rgb |
| Example | char rgb_txt[40]; strcpy( rgb_txt, "r127g127g127" ); pm_rgb ( "Wall color", rgb_txt ); |
pm_tab_begin
int pm_tab_begin ( char
*tab_name );
| Synopsis | #include
"silver.h" The pm_tab_begin begins a new tab in a SIlverScreen panel. |
| Parameters | tab_name is a pointer to character buffer that contains the name to use on the new tab. |
| See Also | pm_tab_initialize |
pm_tab_initialize
int pm_tab_initialize (
char *dialog_name );
| Synopsis | #include
"silver.h" The pm_tab_initialize is similar to pm_initialize, except that it specifies that the panel being defined is a tabbed dialog. |
| Parameters | dialog_name is a pointer to character buffer that contains the name to use in the title bar of the dialog. |
| See Also | pm_tab_begin, pm_initialize |
pm_text
void pm_text ( char
*message, char *buf, int mandatory, int length )
char *message; // prompt string
char *buf; // address of buffer to receive result string
int mandatory; // mandatory entry flag
int length; // maximum length of string
| Synopsis | #include
"silver.h" The pm_text function adds a prompt for a string to the current panel, with prompt specified by message. length is the maximum length of the text data. If mandatory is 1, a value must be entered for the item. If mandatory is 0, then the initial value can be accepted without change. After pm_execute, the resulting value is returned in buf. |
| Parameters | message is a null-terminated string containing the prompt message. buf is the address of a character buffer which is to receive the string. mandatory is an integer specifying whether entry for this field is mandatory or not. length is an integer specifying the maximum length of the input string. |
| See Also | pm_execute |
pm_xyz
void pm_xyz ( char
*message, SS_XYZ *pt )
char *message; // prompt string
SS_XYZ *pt; // address of 3D point to receive result
| Synopsis | #include
"silver.h" The pm_xyz function adds a prompt for a 3D point to the current panel, with prompt specified by message. When the panel is displayed, the user will have the option of picking a point in the drawing; the result of such a pick will be stored into pt. |
| Parameters | message is a null-terminated string containing the prompt message. pt is the address of a 3D point that is to receive the result. |
| See Also | pm_execute |
point_on_line
int point_on_line (
SS_XYZ *p1, SS_XYZ *p2, SS_XYZ *p3 )
SS_XYZ *p1; // address of a 3D point
SS_XYZ *p2; // address of a 3D point
SS_XYZ *p3; // address of a 3D point
| Synopsis | #include
"silver.h" The point_on_line function determines whether or not point at p1 lies on the line segment defined by the points at p2-p3. |
| Parameters | p1, p2 and p3 are all addresses of 3D points. |
| Return Value | point_on_line returns 1 if the point lies on the line segment, and 0 if not. |
| See Also | point_on_plane |