GSURF Library

GS_init_view()

Performs initial matrix loading and sets up a default projection.

GS_set_focus(realto)
float realto[3];

Selects a point in geographic space to be the center of focus, to hold in the center of view as viewer position changes.

GS_set_focus_center_map(id)
int id;

Convenience function to set focus to center of a given surface with handle id.

GS_get_focus(realto)
float realto[3];

Returns in realto the geographic coordinates of the focal point.

GS_set_nofocus()

Removes any existing focal point, causing direction of view to remain fixed as viewer position changes.

GS_set_fov(fov)
int fov;

Sets field of view (in vertical direction), where fov is expressed as tenths of degrees.

int GS_get_fov()

Returns current field of view, in 10ths of degrees.

GS_set_viewdir(dir)
float dir[3];

Sets the view direction to that of the vector dir. If focus is on, it will be overridden and disabled until reset.

GS_get_viewdir(dir)
float dir[3];

Returns current view direction as a unit vector dir.

GS_get_from(fr)
float *fr;

The from-to vector is the viewing direction, using modeling coordinates as "from" and "to" points. GS_get_from_real transforms the "from" coordinates to return geographic coordinates for the viewer position.

GS_set_twist(t)
int t;

Twist refers to the amount the view is tilted t is tenths of degrees clockwise from 12:00.

int GS_get_twist()

int GS_look_here(sx, sy)
int sx, 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(pt)
float *pt;

GS_moveto_real(pt)
float *pt;

GS_set_global_exag(exag)
float exag;

float GS_global_exag()

GS_save_3dview(vname, surfid)
char *vname;
int surfid;

GS_load_3dview(vname, surfid)
char *vname;
int surfid;

int GS_new_light()

GS_setlight_ambient(num, red, green, blue)
int num;
float red, green, blue; /* 0.0 to 1.0 */

GS_setlight_color(num, red, green, blue)
int num;
float red, green, blue; /* 0.0 to 1.0 */

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

GS_switchlight(num, on)
int num, on;

GS_lights_on()

GS_lights_off()

GS_draw_lighting_model()

GS_get_modelposition(siz, pos)
float *siz, pos[3];

Retrieves coordinates for lighting model position, at center of view, (nearclip * 2) from eye.

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

GS_new_surface()

GS_delete_surface(id)
int id;

GS_surf_exists(id)
int id;

int GS_num_surfs()

GS_get_surf_list(numsurfs)
int *numsurfs;

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

GS_set_att_const(id, att, constant)
nt id, att;
float constant;

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

GS_unset_att(id, att)
int id, att;

GS_update_curmask(id)
int id;

GS_update_normals(id)
int id;

GS_draw_surf(id)
int id;

GS_draw_wire(id)
int id;

GS_alldraw_surf()

GS_alldraw_wire()

GS_draw_X(id, pt)
int id;
float *pt;

pt only has to have an X & Y value in true world coordinates

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

GS_set_drawmode(id, mode)
int id, mode;

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

GS_setall_drawmode(mode)
int mode;

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

GS_set_fencecolor(mode)
int mode;

GS_set_wire_color(id, colr)
int id, colr;

GS_get_drawmode(id, mode)
int id, mode;

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

GS_get_wire_color(id, colr)
int id;
int *colr;

GS_set_maskmode(id, mode)
int id, mode;

GS_set_nozero(id, att, mode)
int id, att, mode;

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

GS_get_maskmode(id, mode)
int id, mode;

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

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

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

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

GS_get_zextents(id, min, max, mid)
int id;
float *min, *max, *mid;

Returns Z extents for a single surface.

GS_get_zrange(min, max, doexag)
float *min, *max;
int doexag;

Returns Z extents for all loaded surfaces.

GS_get_zrange_nz(min, max)
float *min, *max;

Returns Z extents for all loaded surfaces, treating zeros as "no data".

int GS_has_transparency()

GS_is_masked(id, pt)
int id;
float *pt;

GS_transp_is_set()

GS_set_SDscale(scale)
float scale;

GS_set_SDsurf(id)
int id;

GS_get_SDscale(scale)
float *scale;

GS_get_SDsurf(id)
int id;

GS_unset_SDsurf()

GS_get_exag_guess(id, exag)
int id;
float *exag;

GS_set_exag(id, exag)
int id;
float exag;

int GS_get_selected_point_on_surface(sx, sy, id, x, y, z)
int sx, sy;
int *id;
float *x, *y, *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_distance_alongsurf(hs, x1, y1, x2, y2, dist/
int hs, use_exag;
float x1, y1, x2, y2, *dist;

Returns distance following terrain.

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

GS_get_val_at_xy(id, att, valstr, x, y)
int id;
char *valstr;
float x, 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

int GV_new_vector()

GV_delete_vector(id)
int id;

GV_vect_exists(id)
int id;

int GV_num_vects()

int *GV_get_vect_list(numvects)
int *numvects;

USER must free when no longer needed!

GV_get_vectname(id, filename)
int id;
char *filename;

GV_load_vector(id, filename)
int id;
char *filename;

GV_select_surf(hv, hs)
int hv, hs;

Select surface identified by hs to have vector identified by hv draped over it.

GV_surf_is_selected(hv, hs)
int hv, hs;

GV_unselect_surf(hv, hs)
int hv, hs;

GV_draw_vect(vid)
int id;

GV_alldraw_vect()

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

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

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

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

int GP_new_site()

GP_delete_site(id)
int id;

GP_site_exists(id)
int id;

int GP_num_sites()

int *GP_get_site_list(numsites)
int *numsites;

USER must free when no longer needed!

GP_get_sitename(id, filename)
int id;
char *filename;

GP_load_site(id, filename)
int id;
char *filename;

GP_select_surf(hp, hs)
int hp, hs;

GP_surf_is_selected(hp, hs)
int hp, hs;

GP_unselect_surf(hp, hs)
int hp, hs;

GP_draw_site(id)
int id;

GP_alldraw_site()

GP_attmode_color(id, filename)
int id;
char *filename;

GP_attmode_none(id)
int id;

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

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

GP_get_zmode(id, use_z)
int id, *use_z;

GP_set_sitemode(id, atmod, color, width, size, mar/
int id, atmod, color, width, marker;
float size;

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

GP_set_zmode(id, use_z)
int id, use_z;

int GVL_new_vol()

GVL_delete_volume(id)
int id;

int GVL_vol_exists(id)
int id;

int GVL_num_vol()

int *GVL_get_vol_list(numvols)
int *numvols;

GVL_get_volname(id, filename)
int id;
char *filename;

GVL_load_volume(id, filename)
int id;
char *filename;

GVL_draw_vol(vid)
int id;

GVL_alldraw_vol()

GVL_draw_fastvol(vid)
int vid;

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

GVL_get_volmode(id, viztype)
int id, *viztype;

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

GVL_set_volmode(id, viztype)
int id, viztype;

GS_set_cplane(num)
int num;

GS_unset_cplane(num)
int cplane;

GS_draw_cplane(num)
int num;

GS_draw_cplane_fence(hs1, hs2, num)
int hs1, hs2, num;

GS_alldraw_cplane_fences ()

int GS_get_fencecolor()

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

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

GK_add_key(pos,fmask,force_replace,precis)
float pos, precis;
unsigned long fmask;
int force_replace;

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.

GK_delete_key(pos, precis, justone)
float pos, 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.

GK_move_key(oldpos, precis, newpos)
float oldpos, newpos, precis;

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).

void GK_clear_keys()

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

GK_do_framestep(step, render)
int step, 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.

GK_set_interpmode(mode)
int mode;

Sets interpolation mode to KF_LINEAR or KF_SPLINE

void GK_set_numsteps(newsteps)
int newsteps;

Sets the number of frames to be interpolated from keyframes.

GK_set_tension(tens)
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(flag)

Draws the current path.

GK_show_site(flag)
int flag;

GK_show_vect(flag)
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()

float GSU_P2distance (from, to)
float *from, *to;

GSU_distance (from, to)
float *from, *to;

double GSU_geodistance (from, to, units)
double *from, *to;
char *units;

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.

GSU_v2dir(v1, v2, v3)
float v1[2], v2[2], v3[2];

GSU_v3dir(v1, v2, v3)
float v1[3], v2[3], v3[3];

GSU_v3mag(v1, mag)
float v1[3], *mag;

GSU_v3norm(v1)
float v1[3];

Changes v1 so that it is a unit vector

GSU_dv3norm(dv1)
double dv1[3];

Changes v1 so that it is a unit vector

GSU_v3normalize(v1, v2)
float v1[3], v2[3];

Changes v2 so that v1v2 is a unit vector

GSU_v3eq(v1, v2)
float v1[3], v2[3];

GSU_v3add(v1, v2)
float v1[3], v2[3];

GSU_v3sub(v1, v2)
float v1[3], v2[3];

v1 -= v2

GSU_v3mult(v1, k)
float v1[3], k;

v1 *= k

GSU_v3cross(v1, v2, v3)
float v1[3], v2[3], v3[3];

returns the cross product v3 = v1 cross v2