Document GisViewer

diff --git a/src/gis-viewer.c b/src/gis-viewer.c
index db244a43d4a132f5ee8136175037982f56a6fea6..141fd6593066c8925c912691296e36791c5d6ed4 100644 (file)
--- a/src/gis-viewer.c
+++ b/src/gis-viewer.c
@@ -15,6 +15,16 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gis-viewer
+ * @short_description: Virtual globe base class
+ *
+ * #GisViewer 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. 
+ */
+
 #include <config.h>
 #include <math.h>
 #include <gtk/gtk.h>
@@ -168,6 +178,15 @@ static void on_view_changed(GisViewer *viewer,
 /***********
  * Methods *
  ***********/
+/**
+ * gis_viewer_setup:
+ * @viewer:  the viewer
+ * @plugins: a plugins store
+ * @prefs:   a prefs store
+ *
+ * This should be called by objects which implement GisViewer somewhere in their
+ * constructor.
+ */
 void gis_viewer_setup(GisViewer *viewer, GisPlugins *plugins, GisPrefs *prefs)
 {
        viewer->plugins = plugins;
@@ -175,6 +194,13 @@ void gis_viewer_setup(GisViewer *viewer, GisPlugins *plugins, GisPrefs *prefs)
        viewer->offline = gis_prefs_get_boolean(prefs, "gis/offline", NULL);
 }
 
+/**
+ * gis_viewer_set_time:
+ * @viewer: the viewer
+ * @time: the time to set the view to
+ *
+ * Set the current time for the view
+ */
 void gis_viewer_set_time(GisViewer *viewer, const char *time)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -184,6 +210,14 @@ void gis_viewer_set_time(GisViewer *viewer, const char *time)
        _gis_viewer_emit_time_changed(viewer);
 }
 
+/**
+ * gis_viewer_get_time:
+ * @viewer: the viewer
+ * 
+ * Get the time that is being viewed
+ *
+ * Returns: the current time
+ */
 gchar *gis_viewer_get_time(GisViewer *viewer)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -191,6 +225,15 @@ gchar *gis_viewer_get_time(GisViewer *viewer)
        return viewer->time;
 }
 
+/**
+ * gis_viewer_set_location:
+ * @viewer: the viewer
+ * @lat:  the new latitude
+ * @lon:  the new longitude
+ * @elev: the new elevation
+ *
+ * Set the location for the camera
+ */
 void gis_viewer_set_location(GisViewer *viewer, gdouble lat, gdouble lon, gdouble elev)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -202,6 +245,15 @@ void gis_viewer_set_location(GisViewer *viewer, gdouble lat, gdouble lon, gdoubl
        _gis_viewer_emit_location_changed(viewer);
 }
 
+/**
+ * gis_viewer_get_location:
+ * @viewer: the viewer
+ * @lat:  the location to store the latitude
+ * @lon:  the location to store the longitude
+ * @elev: the location to store the elevation
+ *
+ * Get the location of the camera
+ */
 void gis_viewer_get_location(GisViewer *viewer, gdouble *lat, gdouble *lon, gdouble *elev)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -211,6 +263,18 @@ void gis_viewer_get_location(GisViewer *viewer, gdouble *lat, gdouble *lon, gdou
        *elev = viewer->location[2];
 }
 
+/**
+ * gis_viewer_pan:
+ * @viewer: the viewer
+ * @forward:  distance to move forward in meters
+ * @right:    distance to move right in meters
+ * @up:       distance to move up in meters
+ *
+ * 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
+ */
 void gis_viewer_pan(GisViewer *viewer, gdouble forward, gdouble sideways, gdouble up)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -232,6 +296,13 @@ void gis_viewer_pan(GisViewer *viewer, gdouble forward, gdouble sideways, gdoubl
        _gis_viewer_emit_location_changed(viewer);
 }
 
+/**
+ * gis_viewer_zoom:
+ * @viewer: the viewer
+ * @scale: the scale to multiple the elevation by
+ *
+ * Multiple the elevation by a scale.
+ */
 void gis_viewer_zoom(GisViewer *viewer, gdouble scale)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -240,6 +311,15 @@ void gis_viewer_zoom(GisViewer *viewer, gdouble scale)
        _gis_viewer_emit_location_changed(viewer);
 }
 
+/**
+ * gis_viewer_set_rotation:
+ * @viewer: the viewer
+ * @x: rotation new around the x axes
+ * @y: rotation new around the y axes
+ * @z: rotation new around the z axes
+ *
+ * Set the rotations in degrees around the x, y, and z axes.
+ */
 void gis_viewer_set_rotation(GisViewer *viewer, gdouble x, gdouble y, gdouble z)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -250,6 +330,15 @@ void gis_viewer_set_rotation(GisViewer *viewer, gdouble x, gdouble y, gdouble z)
        _gis_viewer_emit_rotation_changed(viewer);
 }
 
+/**
+ * gis_viewer_get_rotation:
+ * @viewer: the viewer
+ * @x: rotation around the x axes
+ * @y: rotation around the y axes
+ * @z: rotation around the z axes
+ *
+ * Get the rotations in degrees around the x, y, and z axes.
+ */
 void gis_viewer_get_rotation(GisViewer *viewer, gdouble *x, gdouble *y, gdouble *z)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -259,6 +348,15 @@ void gis_viewer_get_rotation(GisViewer *viewer, gdouble *x, gdouble *y, gdouble
        *z = viewer->rotation[2];
 }
 
+/**
+ * gis_viewer_rotate:
+ * @viewer: the viewer
+ * @x: rotation around the x axes
+ * @y: rotation around the y axes
+ * @z: rotation around the z axes
+ *
+ * Add to the rotation around the x, y, and z axes.
+ */
 void gis_viewer_rotate(GisViewer *viewer, gdouble x, gdouble y, gdouble z)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -269,12 +367,27 @@ void gis_viewer_rotate(GisViewer *viewer, gdouble x, gdouble y, gdouble z)
        _gis_viewer_emit_rotation_changed(viewer);
 }
 
+/**
+ * gis_viewer_refresh:
+ * @viewer: the viewer
+ *
+ * Trigger the refresh signal. This will cause any remote data to be checked for
+ * updates. 
+ */
 void gis_viewer_refresh(GisViewer *viewer)
 {
        g_debug("GisViewer: refresh");
        _gis_viewer_emit_refresh(viewer);
 }
 
+/**
+ * gis_viewer_set_offline:
+ * @viewer: the viewer
+ * @offline: %TRUE to enter offline mode
+ *
+ * Set the offline mode. If @offline is %TRUE, only locally cached data will be
+ * used.
+ */
 void gis_viewer_set_offline(GisViewer *viewer, gboolean offline)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -284,6 +397,14 @@ void gis_viewer_set_offline(GisViewer *viewer, gboolean offline)
        _gis_viewer_emit_offline(viewer);
 }
 
+/**
+ * gis_viewer_get_offline:
+ * @viewer: the viewer
+ *
+ * Check if the viewer is in offline mode.
+ *
+ * Returns: %TRUE if the viewer is in offline mode.
+ */
 gboolean gis_viewer_get_offline(GisViewer *viewer)
 {
        g_assert(GIS_IS_VIEWER(viewer));
@@ -291,7 +412,19 @@ gboolean gis_viewer_get_offline(GisViewer *viewer)
        return viewer->offline;
 }
 
-/* To be implemented by subclasses */
+/***********************************
+ * To be implemented by subclasses *
+ ***********************************/
+/**
+ * gis_viewer_center_position:
+ * @viewer: the viewer
+ * @lat:  the latitude
+ * @lon:  the longitude
+ * @elev: the elevation
+ *
+ * Center the viewer on a point. This can be used before drawing operations to
+ * center the items a particular location.
+ */
 void gis_viewer_center_position(GisViewer *viewer,
                gdouble lat, gdouble lon, gdouble elev)
 {
@@ -301,6 +434,20 @@ void gis_viewer_center_position(GisViewer *viewer,
        klass->center_position(viewer, lat, lon, elev);
 }
 
+/**
+ * gis_viewer_project:
+ * @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
+ *
+ * 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. #GisMarker.
+ */
 void gis_viewer_project(GisViewer *viewer,
                gdouble lat, gdouble lon, gdouble elev,
                gdouble *px, gdouble *py, gdouble *pz)
@@ -311,6 +458,13 @@ void gis_viewer_project(GisViewer *viewer,
        klass->project(viewer, lat, lon, elev, px, py, pz);
 }
 
+/**
+ * gis_viewer_clear_height_func:
+ * @viewer: the viewer
+ *
+ * Clears the height function for the entire viewer. Useful when an elevation
+ * plugin is unloaded.
+ */
 void gis_viewer_clear_height_func(GisViewer *viewer)
 {
        GisViewerClass *klass = GIS_VIEWER_GET_CLASS(viewer);
@@ -319,6 +473,16 @@ void gis_viewer_clear_height_func(GisViewer *viewer)
        klass->clear_height_func(viewer);
 }
 
+/**
+ * gis_viewer_set_height_func:
+ * @viewer:      the viewer
+ * @tile:        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 tile should be updated.
+ *
+ * Set the height function to be used for a given part of the surface..
+ */
 void gis_viewer_set_height_func(GisViewer *viewer, GisTile *tile,
                GisHeightFunc height_func, gpointer user_data,
                gboolean update)
@@ -329,6 +493,27 @@ void gis_viewer_set_height_func(GisViewer *viewer, GisTile *tile,
        klass->set_height_func(viewer, tile, height_func, user_data, update);
 }
 
+/**
+ * gis_viewer_add:
+ * @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
+ *
+ * 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.
+ *
+ * Returns: a handle to be pass to gis_viewer_remove()
+ */
 gpointer gis_viewer_add(GisViewer *viewer, GisObject *object,
                gint level, gboolean sort)
 {
@@ -338,6 +523,16 @@ gpointer gis_viewer_add(GisViewer *viewer, GisObject *object,
        return klass->add(viewer, object, level, sort);
 }
 
+/**
+ * gis_viewer_remove:
+ * @viewer: the viewer
+ * @ref:    the handle obtained from gis_viewer_add()
+ *
+ * Remove an object from the viewer. The objects reference count is decremented
+ * prior to being removed.
+ *
+ * Returns: the #GisObject referenced by the handle
+ */
 GisObject *gis_viewer_remove(GisViewer *viewer, gpointer ref)
 {
        GisViewerClass *klass = GIS_VIEWER_GET_CLASS(viewer);
@@ -390,6 +585,15 @@ static void gis_viewer_class_init(GisViewerClass *klass)
        g_debug("GisViewer: class_init");
        GObjectClass *gobject_class = G_OBJECT_CLASS(klass);
        gobject_class->finalize     = gis_viewer_finalize;
+
+       /**
+        * GisViewer::time-changed:
+        * @viewer: the viewer.
+        * @time:   a string representation of the time.
+        *
+        * The ::time-changed signal is emitted when the viewers current time
+        * changers.
+        */
        signals[SIG_TIME_CHANGED] = g_signal_new(
                        "time-changed",
                        G_TYPE_FROM_CLASS(gobject_class),
@@ -401,6 +605,17 @@ static void gis_viewer_class_init(GisViewerClass *klass)
                        G_TYPE_NONE,
                        1,
                        G_TYPE_STRING);
+
+       /**
+        * GisViewer::location-changed:
+        * @viewer: the viewer.
+        * @lat:    the new latitude.
+        * @lon:    the new longitude.
+        * @elev:   the new elevation.
+        *
+        * The ::location-changed signal is emitted when the viewers camera
+        * location changes.
+        */
        signals[SIG_LOCATION_CHANGED] = g_signal_new(
                        "location-changed",
                        G_TYPE_FROM_CLASS(gobject_class),
@@ -414,6 +629,17 @@ static void gis_viewer_class_init(GisViewerClass *klass)
                        G_TYPE_DOUBLE,
                        G_TYPE_DOUBLE,
                        G_TYPE_DOUBLE);
+
+       /**
+        * GisViewer::rotation-changed:
+        * @viewer: the viewer.
+        * @x: rotation new around the x axes.
+        * @y: rotation new around the y axes.
+        * @z: rotation new around the z axes.
+        *
+        * The ::rotation-changed signal is emitted when the viewers cameras
+        * rotation changes.
+        */
        signals[SIG_ROTATION_CHANGED] = g_signal_new(
                        "rotation-changed",
                        G_TYPE_FROM_CLASS(gobject_class),
@@ -427,6 +653,15 @@ static void gis_viewer_class_init(GisViewerClass *klass)
                        G_TYPE_DOUBLE,
                        G_TYPE_DOUBLE,
                        G_TYPE_DOUBLE);
+
+       /**
+        * GisViewer::refresh:
+        * @viewer: the viewer.
+        *
+        * 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.
+        */
        signals[SIG_REFRESH] = g_signal_new(
                        "refresh",
                        G_TYPE_FROM_CLASS(gobject_class),
@@ -437,6 +672,15 @@ static void gis_viewer_class_init(GisViewerClass *klass)
                        g_cclosure_marshal_VOID__VOID,
                        G_TYPE_NONE,
                        0);
+
+       /**
+        * GisViewer::offline:
+        * @viewer:  the viewer.
+        * @offline: %TRUE if the viewer going offline.
+        *
+        * The ::offline signal is emitted when the viewers offline mode
+        * changes.
+        */
        signals[SIG_OFFLINE] = g_signal_new(
                        "offline",
                        G_TYPE_FROM_CLASS(gobject_class),

diff --git a/src/gis-viewer.h b/src/gis-viewer.h
index ba92b494c5f9db93475c6e02b8adfe7c7c066029..b85120b3d978b62a8a9fc90f2481c786d5780d14 100644 (file)
--- a/src/gis-viewer.h
+++ b/src/gis-viewer.h
@@ -22,9 +22,37 @@
 #include <glib-object.h>
 
 /* Rendering levels */
+/**
+ * GIS_LEVEL_BACKGROUND: 
+ *
+ * The level used to draw background objects (stars, atmosphere, etc).
+ */
 #define GIS_LEVEL_BACKGROUND -100
+
+/**
+ * GIS_LEVEL_WORLD: 
+ *
+ * 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
+ * %GIS_LEVEL_WORLD;
+ */
 #define GIS_LEVEL_WORLD         0
+
+/**
+ * GIS_LEVEL_OVERLAY: 
+ *
+ * The level used to draw screen overlays. These will be drawn in front of most
+ * of ther objects. Text and markers should use %GIS_LEVEL_OVERLAY.
+ */
 #define GIS_LEVEL_OVERLAY     100
+
+/**
+ * GIS_LEVEL_HUD: 
+ *
+ * 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.
+ */
 #define GIS_LEVEL_HUD         200
 
 /* Type macros */
@@ -38,6 +66,16 @@
 typedef struct _GisViewer      GisViewer;
 typedef struct _GisViewerClass GisViewerClass;
 
+/**
+ * GisHeightFunc:
+ * @lat:       the target latitude
+ * @lon:       the target longitude
+ * @user_data: user data passed to the function
+ *
+ * Determine the surface elevation (ground level) at a given point.
+ *
+ * Returns: the elevation in meters above sea level
+ */
 typedef gdouble (*GisHeightFunc)(gdouble lat, gdouble lon, gpointer user_data);
 
 #include "gis-plugin.h"