From 2b517cba642699c307af4089f94280d9b61e3dff Mon Sep 17 00:00:00 2001 From: Andy Spencer Date: Mon, 8 Feb 2010 22:24:41 +0000 Subject: [PATCH] Document GisViewer --- src/gis-viewer.c | 246 ++++++++++++++++++++++++++++++++++++++++++++++- src/gis-viewer.h | 38 ++++++++ 2 files changed, 283 insertions(+), 1 deletion(-) diff --git a/src/gis-viewer.c b/src/gis-viewer.c index db244a4..141fd65 100644 --- a/src/gis-viewer.c +++ b/src/gis-viewer.c @@ -15,6 +15,16 @@ * along with this program. If not, see . */ +/** + * 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 #include #include @@ -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 ba92b49..b85120b 100644 --- a/src/gis-viewer.h +++ b/src/gis-viewer.h @@ -22,9 +22,37 @@ #include /* 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" -- 2.43.2