## GritsViewer GritsViewer — Virtual globe base class |

## Synopsis

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

## 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_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.

### 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_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`;

### 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

### enum GritsProj

    typedef enum {
    	GRITS_PROJ_LATLON,
    	GRITS_PROJ_MERCATOR,
    } GritsProj;

### 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 (*unproject)        (GritsViewer *viewer,
    	                          gdouble px, gdouble py,gdouble pz,
    	                          gdouble *lat, gdouble *lon, gdouble *elev);

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

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

### grits_viewer_add ()

    void                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

### 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_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_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_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_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_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_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_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 longitude
`elev` : | the elevation
`px` : | the project x coordinate
`py` : | the project y coordinate
`pz` : | the project z coordinate

### grits_viewer_queue_draw ()

    void                grits_viewer_queue_draw             (GritsViewer *viewer);

Causes the viewer to redraw the screen. This has the safe effect as gtk_widget_queue_draw, but is thread safe, and probably faster.

`viewer` : | the viewer

### 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_remove ()

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

Remove an object from the viewer.

`viewer` : | the viewer
`object` : | the object to remove

### 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_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_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_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_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_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_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_unproject ()

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

Project a x, y point in screen space to a latitude, longitude, and elevation point. Useful for finding the position of the cursor or another on-screen object in world coordinates.

`viewer` : | the viewer
`lat` : | the latitude
`lon` : | the longitude
`elev` : | the elevation

### 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

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