/*! \page ogsflib GRASS openGL gsurf OGSF Library GRASS openGL gsurf OGSF Library \section ogsfintro OGSF Library for OpenGL programming (gsurf)

Author: Bill Brown GMSL/University of Illinois Overview

The OGSF (gsurf) library, consisting of approximately 20,000 lines of C code, contains some 180 public functions and about twice as many internal functions for run-time data storage, manipulation, querying, and visualization using OpenGL. The library handles all drawing and lighting operations, including use of user-defined clipping planes and drawing various style "fences" on clipping planes when drawing multiple surfaces, and treats datasets as objects which can be used for various attributes of the rendering. It allows data sharing (e.g., same data for more than one attribute of same or different surfaces) , separate masking for each surface, multiple surfaces, vector sets, or point sets, and will also allow multiple volumes. The library provides all query features such as 3D "point on surface", keyframe animation routines, and full state saving functionality. Database-specific routines for interfacing with the GRASS GISlib are kept isolated for easier library reuse with other databases. The gsurf library is not dependent upon any particular interface library, and has been used successfully with both Motif and Tcl/Tk. It is used for NVIZ visualization tool.

The library is designed to provide a unique "handle" or identifier number to the calling program for each new geographic object added to the model. The object could be a surface, vector set, or point set, which could each be defined by one or more database files. Once created, the application only needs to keep track of the "handles" to the objects (which are returned by the creation routines) ; for example, to draw a surface the application would make the call:

GS_draw_surf(id)

where id is the handle number. To associate a vector set with a surface and then draw all surfaces with the vector set draped over the one selected, the application would use the calls:

GV_select_surf(vid, sid)

GS_alldraw_surf()

GV_draw_vect(vid)

where vid and sid are the handles for the vector set and surface. Similarly, to query or change attributes of the object, the handle is used in conjunction with the new attribute, as in: GV_set_vectmode(id, mem, color, width) \subsection Naming_Conventions Naming Conventions

The following naming conventions for function prefixes are used:

Programmers' documentation is currently incomplete, but see the following for more details of the library design and capabilities in the appendix (PLEASE ADD EXPLANATIONS!!):

\section Public_function_prototypes Public function prototypes \subsection Function_Prototypes_for_gsurf_Library Function Prototypes for gsurf Library \subsection gs_init Initialization and positioning (GS) Functions which have to do with loading & manipulating surfaces. Also functions for library initialization, setting global variables, viewer positioning, and lighting.

void *GS_Get_ClientData(int id)

float GS_P2distance (float *from, float *to)

GS_Set_ClientData(int id, void *clientd)

GS_alldraw_cplane_fences()

GS_alldraw_surf()

GS_alldraw_wire()

GS_background_color()

int GS_check_cancel()

GS_clear(int col)

GS_default_draw_color()

GS_delete_surface(int id)

GS_distance (float *from, *to)

GS_done_draw()

int GS_draw_X(int id, float *pt) pt only has to have an X & Y value in true world coordinates

GS_draw_cplane(int num)

GS_draw_cplane_fence(int hs1, int hs2, int num)

GS_draw_lighting_model()

GS_draw_line_onsurf(int id, float x1, float y1, float x2, float y2)

GS_draw_surf(int id)

GS_draw_wire(int id)

int GS_dv3norm(double dv1[3]) Changes dv1 so that it is a unit vector

double GS_geodistance(double *from, double *to, char *units) distance between 2 coordinates Returns distance between two geographic coordinates in current projection.

Units is one of: "meters", "miles", "kilometers", "feet", "yards", "nmiles" (nautical miles), "rods", "inches", "centimeters", "millimeters", "micron", "nanometers", "cubits", "hands", "furlongs", "chains".

Default is meters.

GS_get_SDscale(float *scale)

GS_get_SDsurf(int id)

double GS_get_aspect()

GS_get_att(int id, int att, int *set, float *constant, char *mapname)

GS_get_cat_at_xy(int id, int att, char *catstr, float x, float y)

GS_get_dims(int id, int *rows, int *cols)

int GS_get_distance_alongsurf(int hs, int use_exag, float x1, float y1, float x2, float y2, float *dist) Returns distance following terrain.

GS_get_drawmode(int id, int mode)

GS_get_drawres(int id, int *xres, int *yres, int *xwire, int *ywire)

GS_get_exag_guess(int id, float *exag)

int GS_get_fencecolor()

GS_get_focus(float *realto)

int GS_get_fov() Returns field of view, in 10ths of degrees.

GS_get_from(float *fr)

GS_get_from_real(float *fr)

GS_get_longdim(float *dim)

GS_get_maskmode(int id, int mode)

int GS_get_modelposition(float *siz, float pos[3]) Retrieves coordinates for lighting model position, at center of view, (nearclip * 2) from eye.

GS_get_nozero(int id, int att, int *mode)

GS_get_region(float *n, float *s, float *w, float *e)

GS_get_scale(float *sx, float *sy, float *sz, int doexag)

int GS_get_selected_point_on_surface(int sx, int sy, int *id, float *x, float *y, float *z) Given screen coordinates sx & sy, find closest intersection of view ray with surfaces and return coordinates of intersection in x, y, z, and identifier of surface in id.

Returns 0 if no intersections found, otherwise number of intersections.

GS_get_surf_list(int *numsurfs)

GS_get_to(float *to)

GS_get_trans(int id, float *xtrans, float *ytrans, float *ztrans)

int GS_get_twist()

int GS_get_val_at_xy(int id, char *att, char *valstr, float x, float y) Prints "NULL" or the value (i.e., "921.5") to valstr.

Colors are translated to rgb and returned as Rxxx Gxxx Bxxx

Usually call after GS_get_selected_point_on_surface

Returns -1 if point outside of window or masked, otherwise 1

GS_get_viewdir(float dir[3])

GS_get_wire_color(int id, int *colr)

int GS_get_zextents(int id, float *min, float *max, float *mid) Returns Z extents for a single surface.

int GS_get_zrange(float *min, float *max, int doexag) Returns Z extents for all loaded surfaces.

int GS_get_zrange_nz(float *min, float *max) Returns Z extents for all loaded surfaces, treating zeros as "no data".

float GS_global_exag()

int GS_has_transparency()

GS_init_view()

GS_is_masked(int id, float *pt)

GS_libinit()

GS_lights_off()

GS_lights_on()

GS_load_3dview(char *vname, int surfid)

GS_load_att_map(int id, char *filename, int att)

int GS_look_here(int sx, int sy) Reset center of view to screen coordinates sx, sy.

Send screen coords sx & sy, lib traces through surfaces & sets new center to point of nearest intersection. If no intersection, uses line of sight with length of current view ray (eye to center) to set new center.

GS_moveto(float *pt)

GS_moveto_real(float *pt)

int GS_new_light()

GS_new_surface()

int GS_num_surfs()

GS_ready_draw()

GS_save_3dview(char *vname, int surfid)

GS_set_SDscale(float scale)

GS_set_SDsurf(int id)

GS_set_att_const(int id, int att, float constant)

GS_set_att_defaults(float defs[MAX_ATTS], null_defs[MAX_ATTS])

GS_set_cancel(int c)

GS_set_cplane(int num)

GS_set_cplane_rot(int num, float dx, float dy, float dz)

GS_set_cplane_trans(int num, float dx, float dy, float dz)

GS_set_cxl_func(void (*f) () )

int GS_set_draw(int where) Sets which buffer to draw to.

where should be one of: GSD_BOTH, GSD_FRONT, GSD_BACK

GS_set_drawmode(int id, int mode)

GS_set_drawres(int id, int xres, int yres, int xwire, int ywire)

GS_set_exag(int id, float exag)

GS_set_fencecolor(int mode)

GS_set_focus(float *realto)

GS_set_focus_center_map(int id)

GS_set_fov(int fov)

GS_set_global_exag(float exag)

GS_set_maskmode(int id, int mode)

GS_set_nofocus()

GS_set_nozero(int id, int att, int mode)

GS_set_swap_func(void (*f) () )

GS_set_trans(int id, float xtrans, float ytrans, float ztrans)

int GS_set_twist(int t) t is tenths of degrees clockwise from 12:00.

GS_set_viewdir(float dir[3])

GS_set_viewport(int left, int right, int bottom, int top)

GS_set_wire_color(int id, int colr)

GS_setall_drawmode(int mode)

GS_setall_drawres(int xres, int yres, int xwire, int ywire)

int GS_setlight_ambient(int num, float red, float green, float blue) Red, green, blue from 0.0 to 1.0

int GS_setlight_color(int num, float red, float green, float blue) Red, green, blue from 0.0 to 1.0

GS_setlight_position(int num, float xpos, float ypos, float zpos, int local)

GS_surf_exists(int id)

GS_switchlight(int num, int on)

GS_transp_is_set()

GS_unset_SDsurf()

GS_unset_att(int id, int att)

GS_unset_cplane(int num)

GS_update_curmask(int id)

GS_update_normals(int id)

GS_v2dir(float v1[2], float v2[2], float v3[2])

GS_v3add(float v1[3], float v2[3])

int GS_v3cross(float v1[3], float v2[3], float v3[3]) returns the cross product v3 = v1 cross v2

GS_v3dir(float v1[3], float v2[3], float v3[3)

GS_v3eq(float v1[3], float v2[3])

GS_v3mag(float v1[3], float *mag)

int GS_v3mult(float v1[3], float k) v1 *= k

int GS_v3norm(float v1[3]) Changes v1 so that it is a unit vector

int GS_v3normalize(float v1[3], float v2[3]) Changes v2 so that v1v2 is a unit vector

int GS_v3sub(float v1[3], float v2[3]) v1 -= v2 \subsection gv_vect Loading and manipulation of vector maps (GV) Functions which have to do with loading & manipulating vector sets.

void *GV_Get_ClientData(int id)

GV_Set_ClientData(int id, int clientd)

GV_alldraw_vect()

GV_delete_vector(int id)

GV_draw_fastvect(int vid)

GV_draw_vect(int vid)

GV_get_trans(int id, float *xtrans, float *ytrans, float *ztrans)

int *GV_get_vect_list(int *numvects) USER must free when no longer needed!

GV_get_vectmode(int id, int *mem, int *color, int *width)

GV_get_vectname(int id, char *filename)

GV_load_vector(int id, char *filename)

int GV_new_vector()

int GV_num_vects()

int GV_select_surf(int hv, int hs) Select surface identified by hs to have vector identified by hv draped over it.

GV_set_trans(int id, float xtrans, float ytrans, float ztrans)

GV_set_vectmode(int id, int mem, int color, int width)

GV_surf_is_selected(int hv, int hs)

GV_unselect_surf(int hv, int hs)

GV_vect_exists(int id) \subsection gp_points Loading and manipulation of point maps (GP) Functions which have to do with loading & manipulating point sets.

void *GP_Get_ClientData(int id)

GP_Set_ClientData(int id, void *clientd)

GP_alldraw_site()

GP_attmode_color(int id, char *filename)

GP_attmode_none(int id)

GP_delete_site(int id)

GP_draw_site(int id)

int *GP_get_site_list(int *numsites) USER must free when no longer needed!

GP_get_sitemode(int id, int *atmod, int *color, int *width, float *size, int *marker)

GP_get_sitename(int id, char *filename)

GP_get_trans(int id, float *xtrans, float *ytrans, float *ztrans)

GP_get_zmode(int id, int *use_z)

GP_load_site(int id, char *filename)

int GP_new_site()

int GP_num_sites()

GP_select_surf(int hp, int hs)

GP_set_sitemode(int id, int atmod, int color, int width, float size, int marker)

GP_set_trans(int id, float *xtrans, float *ytrans, float *ztrans)

GP_set_zmode(int id, int use_z)

GP_site_exists(int id)

GP_surf_is_selected(int hp, int hs)

GP_unselect_surf(int hp, int hs) \subsection gk_keyframes Keyframe animation Functions which have to do with setting & manipulating keyframes for viewer position animation (fly-bys).

int GK_add_key(float pos, unsigned long fmask, int force_replace, float precis) The pos value is the relative position in the animation for this particular keyframe - used to compare relative distance to neighboring keyframes, it can be any floating point value.

The fmask value can be any of the following or'd together: KF_FROMX_MASK KF_FROMY_MASK KF_FROMZ_MASK KF_FROM_MASK (KF_FROMX_MASK | KF_FROMY_MASK | KF_FROMZ_MASK)

KF_DIRX_MASK KF_DIRY_MASK KF_DIRZ_MASK KF_DIR_MASK (KF_DIRX_MASK | KF_DIRY_MASK | KF_DIRZ_MASK)

KF_FOV_MASK KF_TWIST_MASK

KF_ALL_MASK (KF_FROM_MASK | KF_DIR_MASK | KF_FOV_MASK | KF_TWIST_MASK)

Other fields will be added later.

The value precis and the boolean force_replace are used to determine if a keyframe should be considered to be at the same position as a pre-existing keyframe. e.g., if anykey.pos - newkey.pos <= precis, GK_add_key() will fail unless force_replace is TRUE.

Returns 1 if key is added, otherwise -1.

void GK_clear_keys() Deletes all keyframes, resets field masks. Doesn't change number of frames requested.

int GK_delete_key(float pos, float precis, int justone) The values pos & precis are used to determine which keyframes to delete. Any keyframes with their position within precis of pos will be deleted if justone is zero. If justone is non-zero, only the first (lowest pos) keyframe in the range will be deleted.

Returns number of keys deleted.

int GK_do_framestep(int step, int render) Moves the animation to frame number "step". Step should be a value between 1 and the number of frames. If render is non-zero, calls draw_all.

int GK_move_key(float oldpos, float precis, float newpos) Precis works as in other functions - to identify keyframe to move. Only the first keyframe in the precis range will be moved.

Returns number of keys moved (1 or 0) .

int GK_set_interpmode(int mode) Sets interpolation mode to KF_LINEAR or KF_SPLINE

void GK_set_numsteps(int newsteps) Sets the number of frames to be interpolated from keyframes.

int GK_set_tension(float tens) Sets value for tension when interpmode is KF_SPLINE. The value tens should be between 0.0 & 1.0.

void GK_show_path(int flag) Draws the current path.

GK_show_site(int flag)

GK_show_vect(int flag)

void GK_showtension_start()

void GK_showtension_stop() Use GK_showtension_start/GK_update_tension/GK_showtension_stop to initialize & stop multi-view display of path when changing tension.

void GK_update_frames() Recalculates path using the current number of frames requested. Call after changing number of frames or when Keyframes change.

void GK_update_tension() \subsection gvl_volume Loading and manipulation of volume maps (GVL) Functions which have to do with loading & manipulating 3D volumes.

void *GVL_Get_ClientData(int id)

GVL_Set_ClientData(int id, void *clientd)

GVL_alldraw_vol()

GVL_delete_volume(int id)

GVL_draw_fastvol(int vid)

GVL_draw_vol(int vid)

GVL_get_trans(int id, float *xtrans, float *ytrans, float *ztrans)

int *GVL_get_vol_list(int *numvols)

GVL_get_volmode(int id, int *viztype)

GVL_get_volname(int id, char *filename)

GVL_load_volume(int id, char *filename)

int GVL_new_vol()

int GVL_num_vol()

GVL_set_trans(int id, float xtrans, float ytrans, float ztrans)

GVL_set_volmode(int id, int viztype)

int GVL_vol_exists(int id)

\subsection gsurf_h Public include file gsurf.h See lib/ogsf/gsurf.h \subsection keyframe_h Public include file keyframe.h See lib/ogsf/keyframe.h \subsection rgbpack_h Public color packing utility macros rgbpack.h See lib/ogsf/rgbpack.h \subsection gstypes_h Private types and defines gstypes.h See lib/ogsf/gstypes.h \subsection gsget_h Private utilities gsget.h See lib/ogsf/gsget.h */