GritsViewer

GritsViewer — Virtual globe base class

Synopsis

#define             GRITS_LEVEL_BACKGROUND
#define             GRITS_LEVEL_WORLD
#define             GRITS_LEVEL_OVERLAY
#define             GRITS_LEVEL_HUD
gdouble             (*GritsHeightFunc)                  (gdouble lat,
                                                         gdouble lon,
                                                         gpointer user_data);
struct              GritsViewer;
struct              GritsViewerClass;
void                grits_viewer_setup                  (GritsViewer *viewer,
                                                         GritsPlugins *plugins,
                                                         GritsPrefs *prefs);
void                grits_viewer_set_time               (GritsViewer *viewer,
                                                         time_t time);
time_t              grits_viewer_get_time               (GritsViewer *viewer);
void                grits_viewer_set_location           (GritsViewer *viewer,
                                                         gdouble lat,
                                                         gdouble lon,
                                                         gdouble elev);
void                grits_viewer_get_location           (GritsViewer *viewer,
                                                         gdouble *lat,
                                                         gdouble *lon,
                                                         gdouble *elev);
void                grits_viewer_pan                    (GritsViewer *viewer,
                                                         gdouble forward,
                                                         gdouble right,
                                                         gdouble up);
void                grits_viewer_zoom                   (GritsViewer *viewer,
                                                         gdouble scale);
void                grits_viewer_set_rotation           (GritsViewer *viewer,
                                                         gdouble x,
                                                         gdouble y,
                                                         gdouble z);
void                grits_viewer_get_rotation           (GritsViewer *viewer,
                                                         gdouble *x,
                                                         gdouble *y,
                                                         gdouble *z);
void                grits_viewer_rotate                 (GritsViewer *viewer,
                                                         gdouble x,
                                                         gdouble y,
                                                         gdouble z);
void                grits_viewer_refresh                (GritsViewer *viewer);
void                grits_viewer_set_offline            (GritsViewer *viewer,
                                                         gboolean offline);
gboolean            grits_viewer_get_offline            (GritsViewer *viewer);
void                grits_viewer_center_position        (GritsViewer *viewer,
                                                         gdouble lat,
                                                         gdouble lon,
                                                         gdouble elev);
void                grits_viewer_project                (GritsViewer *viewer,
                                                         gdouble lat,
                                                         gdouble lon,
                                                         gdouble elev,
                                                         gdouble *px,
                                                         gdouble *py,
                                                         gdouble *pz);
void                grits_viewer_clear_height_func      (GritsViewer *viewer);
void                grits_viewer_set_height_func        (GritsViewer *viewer,
                                                         GritsBounds *bounds,
                                                         GritsHeightFunc height_func,
                                                         gpointer user_data,
                                                         gboolean update);
gpointer            grits_viewer_add                    (GritsViewer *viewer,
                                                         GritsObject *object,
                                                         gint level,
                                                         gboolean sort);
GritsObject *       grits_viewer_remove                 (GritsViewer *viewer,
                                                         GritsObject *object);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkDrawingArea
                           +----GritsViewer
                                 +----GritsOpenGL

Implemented Interfaces

GritsViewer implements AtkImplementorIface and GtkBuildable.

Signals

  "location-changed"                               : Run Last
  "offline"                                        : Run Last
  "refresh"                                        : Run Last
  "rotation-changed"                               : Run Last
  "time-changed"                                   : Run Last

Description

GritsViewer is the base class for the virtual globe widget. It handles everything not directly related to drawing the globe. Plugins and applications using the viewer should normally talk to the viewer and not care how it is implemented.

Details

GRITS_LEVEL_BACKGROUND

#define GRITS_LEVEL_BACKGROUND -100

The level used to draw background objects (stars, atmosphere, etc).


GRITS_LEVEL_WORLD

#define GRITS_LEVEL_WORLD         0

The level used to draw world objects. This is for both surface data as well as things in the air or underground. Most objects should use GRITS_LEVEL_WORLD;


GRITS_LEVEL_OVERLAY

#define GRITS_LEVEL_OVERLAY     100

The level used to draw screen overlays. These will be drawn in front of most of ther objects. Text and markers should use GRITS_LEVEL_OVERLAY.


GRITS_LEVEL_HUD

#define GRITS_LEVEL_HUD         200

The level used to draw the Heads Up Display. This is for things that are not anchored at all the the world. They should be drawn in front of everything else.


GritsHeightFunc ()

gdouble             (*GritsHeightFunc)                  (gdouble lat,
                                                         gdouble lon,
                                                         gpointer user_data);

Determine the surface elevation (ground level) at a given point.

lat :

the target latitude

lon :

the target longitude

user_data :

user data passed to the function

Returns :

the elevation in meters above sea level

struct GritsViewer

struct GritsViewer;


struct GritsViewerClass

struct GritsViewerClass {
	GtkDrawingAreaClass parent_class;

	/* class members */
	void (*center_position)  (GritsViewer *viewer,
	                          gdouble lat, gdouble lon, gdouble elev);

	void (*project)          (GritsViewer *viewer,
	                          gdouble lat, gdouble lon, gdouble elev,
	                          gdouble *px, gdouble *py, gdouble *pz);

	void (*clear_height_func)(GritsViewer *viewer);
	void (*set_height_func)  (GritsViewer *viewer, GritsBounds *bounds,
	                          GritsHeightFunc height_func, gpointer user_data,
	                          gboolean update);

	gpointer (*add)          (GritsViewer *viewer, GritsObject *object,
	                          gint level, gboolean sort);
	GritsObject *(*remove)   (GritsViewer *viewer, GritsObject *object);
};


grits_viewer_setup ()

void                grits_viewer_setup                  (GritsViewer *viewer,
                                                         GritsPlugins *plugins,
                                                         GritsPrefs *prefs);

This should be called by objects which implement GritsViewer somewhere in their constructor.

viewer :

the viewer

plugins :

a plugins store

prefs :

a prefs store

grits_viewer_set_time ()

void                grits_viewer_set_time               (GritsViewer *viewer,
                                                         time_t time);

Set the current time for the view

viewer :

the viewer

time :

the time to set the view to

grits_viewer_get_time ()

time_t              grits_viewer_get_time               (GritsViewer *viewer);

Get the time that is being viewed

viewer :

the viewer

Returns :

the current time

grits_viewer_set_location ()

void                grits_viewer_set_location           (GritsViewer *viewer,
                                                         gdouble lat,
                                                         gdouble lon,
                                                         gdouble elev);

Set the location for the camera

viewer :

the viewer

lat :

the new latitude

lon :

the new longitude

elev :

the new elevation

grits_viewer_get_location ()

void                grits_viewer_get_location           (GritsViewer *viewer,
                                                         gdouble *lat,
                                                         gdouble *lon,
                                                         gdouble *elev);

Get the location of the camera

viewer :

the viewer

lat :

the location to store the latitude

lon :

the location to store the longitude

elev :

the location to store the elevation

grits_viewer_pan ()

void                grits_viewer_pan                    (GritsViewer *viewer,
                                                         gdouble forward,
                                                         gdouble right,
                                                         gdouble up);

Pan the location by a number of meters long the surface.

Bugs: the distances are not in meters Bugs: panning does not move in strait lines

viewer :

the viewer

forward :

distance to move forward in meters

right :

distance to move right in meters

up :

distance to move up in meters

grits_viewer_zoom ()

void                grits_viewer_zoom                   (GritsViewer *viewer,
                                                         gdouble scale);

Multiple the elevation by a scale.

viewer :

the viewer

scale :

the scale to multiple the elevation by

grits_viewer_set_rotation ()

void                grits_viewer_set_rotation           (GritsViewer *viewer,
                                                         gdouble x,
                                                         gdouble y,
                                                         gdouble z);

Set the rotations in degrees around the x, y, and z axes.

viewer :

the viewer

x :

rotation new around the x axes

y :

rotation new around the y axes

z :

rotation new around the z axes

grits_viewer_get_rotation ()

void                grits_viewer_get_rotation           (GritsViewer *viewer,
                                                         gdouble *x,
                                                         gdouble *y,
                                                         gdouble *z);

Get the rotations in degrees around the x, y, and z axes.

viewer :

the viewer

x :

rotation around the x axes

y :

rotation around the y axes

z :

rotation around the z axes

grits_viewer_rotate ()

void                grits_viewer_rotate                 (GritsViewer *viewer,
                                                         gdouble x,
                                                         gdouble y,
                                                         gdouble z);

Add to the rotation around the x, y, and z axes.

viewer :

the viewer

x :

rotation around the x axes

y :

rotation around the y axes

z :

rotation around the z axes

grits_viewer_refresh ()

void                grits_viewer_refresh                (GritsViewer *viewer);

Trigger the refresh signal. This will cause any remote data to be checked for updates.

viewer :

the viewer

grits_viewer_set_offline ()

void                grits_viewer_set_offline            (GritsViewer *viewer,
                                                         gboolean offline);

Set the offline mode. If offline is TRUE, only locally cached data will be used.

viewer :

the viewer

offline :

TRUE to enter offline mode

grits_viewer_get_offline ()

gboolean            grits_viewer_get_offline            (GritsViewer *viewer);

Check if the viewer is in offline mode.

viewer :

the viewer

Returns :

TRUE if the viewer is in offline mode.

grits_viewer_center_position ()

void                grits_viewer_center_position        (GritsViewer *viewer,
                                                         gdouble lat,
                                                         gdouble lon,
                                                         gdouble elev);

Center the viewer on a point. This can be used before drawing operations to center the items a particular location.

viewer :

the viewer

lat :

the latitude

lon :

the longitude

elev :

the elevation

grits_viewer_project ()

void                grits_viewer_project                (GritsViewer *viewer,
                                                         gdouble lat,
                                                         gdouble lon,
                                                         gdouble elev,
                                                         gdouble *px,
                                                         gdouble *py,
                                                         gdouble *pz);

Project a latitude, longitude, elevation point to to x, y, and z coordinates in screen space. Useful for drawing orthographic data over a particular point in space. E.g. GritsMarker.

viewer :

the viewer

lat :

the latitude

lon :

the latitude

elev :

the latitude

px :

the project x coordinate

py :

the project y coordinate

pz :

the project z coordinate

grits_viewer_clear_height_func ()

void                grits_viewer_clear_height_func      (GritsViewer *viewer);

Clears the height function for the entire viewer. Useful when an elevation plugin is unloaded.

viewer :

the viewer

grits_viewer_set_height_func ()

void                grits_viewer_set_height_func        (GritsViewer *viewer,
                                                         GritsBounds *bounds,
                                                         GritsHeightFunc height_func,
                                                         gpointer user_data,
                                                         gboolean update);

Set the height function to be used for a given part of the surface..

viewer :

the viewer

bounds :

the area to set the height function for

height_func :

the height function

user_data :

user data to pass to the height function

update :

TRUE if the heights inside the bounds should be updated.

grits_viewer_add ()

gpointer            grits_viewer_add                    (GritsViewer *viewer,
                                                         GritsObject *object,
                                                         gint level,
                                                         gboolean sort);

Objects which are added to the viewer will be drawn on subsequent renderings if their level of details is adequate.

The level represents the order the object should be drawn in, this is unrelated to the objects actual position in the world.

Semi-transparent objects should set sort to TRUE so that they are rendered correctly when they overlap other semi-transparent objects.

The viewer steals the objects reference. Call g_object_ref if you plan on holding a reference as well.

viewer :

the viewer

object :

the object to add

level :

the level to add the object to

sort :

TRUE if the object should be depth-sorted prior to being drawn

Returns :

a handle to be pass to grits_viewer_remove()

grits_viewer_remove ()

GritsObject *       grits_viewer_remove                 (GritsViewer *viewer,
                                                         GritsObject *object);

Remove an object from the viewer. The objects reference count is decremented prior to being removed.

viewer :

the viewer

Returns :

the GritsObject referenced by the handle

Signal Details

The "location-changed" signal

void                user_function                      (GritsViewer *viewer,
                                                        gdouble      lat,
                                                        gdouble      lon,
                                                        gdouble      elev,
                                                        gpointer     user_data)      : Run Last

The ::location-changed signal is emitted when the viewers camera location changes.

viewer :

the viewer.

lat :

the new latitude.

lon :

the new longitude.

elev :

the new elevation.

user_data :

user data set when the signal handler was connected.

The "offline" signal

void                user_function                      (GritsViewer *viewer,
                                                        gboolean     offline,
                                                        gpointer     user_data)      : Run Last

The ::offline signal is emitted when the viewers offline mode changes.

viewer :

the viewer.

offline :

TRUE if the viewer going offline.

user_data :

user data set when the signal handler was connected.

The "refresh" signal

void                user_function                      (GritsViewer *viewer,
                                                        gpointer     user_data)      : Run Last

The ::refresh signal is emitted when a refresh is needed. If you are using real-time data from a remote server, you should connect to the refresh signal and update the data when necessary.

viewer :

the viewer.

user_data :

user data set when the signal handler was connected.

The "rotation-changed" signal

void                user_function                      (GritsViewer *viewer,
                                                        gdouble      x,
                                                        gdouble      y,
                                                        gdouble      z,
                                                        gpointer     user_data)      : Run Last

The ::rotation-changed signal is emitted when the viewers cameras rotation changes.

viewer :

the viewer.

x :

rotation new around the x axes.

y :

rotation new around the y axes.

z :

rotation new around the z axes.

user_data :

user data set when the signal handler was connected.

The "time-changed" signal

void                user_function                      (GritsViewer *viewer,
                                                        glong        time,
                                                        gpointer     user_data)      : Run Last

The ::time-changed signal is emitted when the viewers current time changers.

viewer :

the viewer.

time :

the new time.

user_data :

user data set when the signal handler was connected.