Refactor:core:Add Doxygen docs, #define IMAGE_W_H_UNSET for image dimensions.R6547

6 files changed, 52 insertions, 22 deletions

diff --git a/navit/graphics.c b/navit/graphics.c
index 113c19999..abd18455c 100644
--- a/navit/graphics.c
+++ b/navit/graphics.c
@@ -654,11 +654,12 @@ void graphics_gc_set_dashes(struct graphics_gc *gc, int width, int offset, unsig
 }
 
 /**
- * Create a new image from file path scaled to w and h pixels
+ * @brief Create a new image from file path, optionally scaled to w and h pixels.
+ *
  * @param gra the graphics instance
  * @param path path of the image to load
- * @param w width to rescale to
- * @param h height to rescale to
+ * @param w width to rescale to, or IMAGE_W_H_UNSET for original width
+ * @param h height to rescale to, or IMAGE_W_H_UNSET for original height
  * @returns <>
  * @author Martin Schaller (04/2008)
 */
@@ -684,7 +685,7 @@ image_new_helper(struct graphics *gra, struct graphics_image *this_, char *path,
 			case 1:
 				/* The best variant both for cpu usage and quality would be prescaled png of a needed size */
 				mode++;
-				if (width != -1 && height != -1) {
+				if (width != IMAGE_W_H_UNSET && height != IMAGE_W_H_UNSET) {
 					new_name=g_strdup_printf("%s_%d_%d.png", name, width, height);
 				}
 				break;
@@ -782,12 +783,13 @@ image_new_helper(struct graphics *gra, struct graphics_image *this_, char *path,
 }
 
 /**
- * Create a new image from file path scaled to w and h pixels and possibly rotated
+ * @brief Create a new image from file path, optionally scaled to w and h pixels and rotated.
+ *
  * @param gra the graphics instance
  * @param path path of the image to load
- * @param w width to rescale to
- * @param h height to rescale to
- * @param rotate angle to rotate the image. Warning, graphics might only support 90 degree steps here
+ * @param w width to rescale to, or IMAGE_W_H_UNSET for original width
+ * @param h height to rescale to, or IMAGE_W_H_UNSET for original height
+ * @param rotate angle to rotate the image, in 90 degree steps (not supported by all plugins).
  * @returns <>
  * @author Martin Schaller (04/2008)
 */
@@ -818,7 +820,7 @@ struct graphics_image * graphics_image_new_scaled_rotated(struct graphics *gra,
 		char *pathi=paths[i];
 		int len=strlen(pathi);
 		int i,k;
-		int newwidth=-1, newheight=-1;
+		int newwidth=IMAGE_W_H_UNSET, newheight=IMAGE_W_H_UNSET;
 
 		ext=g_utf8_strrchr(pathi,-1,'.');
 		i=pathi-ext+len;
@@ -855,8 +857,8 @@ struct graphics_image * graphics_image_new_scaled_rotated(struct graphics *gra,
 		}
 		
 		if(k==1 || s<=pathi || *s!='_') {
-			newwidth=-1;
-			newheight=-1;
+			newwidth=IMAGE_W_H_UNSET;
+			newheight=IMAGE_W_H_UNSET;
 			if(ext)
 				s=ext;
 			else
@@ -865,9 +867,9 @@ struct graphics_image * graphics_image_new_scaled_rotated(struct graphics *gra,
 		}
 		
 		/* If exact h and w values were given as function parameters, they take precedence over values guessed from the image name */
-		if(w!=-1)
+		if(w!=IMAGE_W_H_UNSET)
 			newwidth=w;
-		if(h!=-1)
+		if(h!=IMAGE_W_H_UNSET)
 			newheight=h;
 			
 		name=g_strndup(pathi,s-pathi);
@@ -899,7 +901,7 @@ struct graphics_image * graphics_image_new_scaled_rotated(struct graphics *gra,
 */
 struct graphics_image * graphics_image_new(struct graphics *gra, char *path)
 {
-	return graphics_image_new_scaled_rotated(gra, path, -1, -1, 0);
+	return graphics_image_new_scaled_rotated(gra, path, IMAGE_W_H_UNSET, IMAGE_W_H_UNSET, 0);
 }
 
 /**
@@ -2138,7 +2140,7 @@ displayitem_draw(struct displayitem *di, void *dummy, struct display_context *dc
 	case element_image:
 		dbg(lvl_debug,"image: '%s'\n", di->label);
 		if (gra->meth.draw_image_warp) {
-			img=graphics_image_new_scaled_rotated(gra, di->label, -1, -1, 0);
+			img=graphics_image_new_scaled_rotated(gra, di->label, IMAGE_W_H_UNSET, IMAGE_W_H_UNSET, 0);
 			if (img)
 				gra->meth.draw_image_warp(gra->priv, gra->gc[0]->priv, pa, count, img->priv);
 		} else
diff --git a/navit/graphics.h b/navit/graphics.h
index 810355f2d..fb18347cf 100644
--- a/navit/graphics.h
+++ b/navit/graphics.h
@@ -17,6 +17,11 @@
  * Boston, MA  02110-1301, USA.
  */
 
+/** @file
+ *
+ * @brief Exported functions / structures for the graphics subsystem.
+ */
+
 #ifndef NAVIT_GRAPHICS_H
 #define NAVIT_GRAPHICS_H
 
@@ -59,6 +64,16 @@ struct graphics_image_buffer {
 	int len;
 };
 
+/** Magic value for unset/unspecified width/height. */
+#define IMAGE_W_H_UNSET (-1)
+
+/** @brief The functions to be implemented by graphics plugins.
+ *
+ * This struct lists the functions that Navit graphics plugins must implement.
+ * The plugin must supply its list of function implementations from its plugin_init() function.
+ * @see graphics_gtk_drawing_area#plugin_init()
+ * @see graphics_android#plugin_init()
+ */
 struct graphics_methods {
 	void (*graphics_destroy)(struct graphics_priv *gr);
 	void (*draw_mode)(struct graphics_priv *gr, enum draw_mode_num mode);
@@ -74,6 +89,19 @@ struct graphics_methods {
 	struct graphics_gc_priv *(*gc_new)(struct graphics_priv *gr, struct graphics_gc_methods *meth);
 	void (*background_gc)(struct graphics_priv *gr, struct graphics_gc_priv *gc);
 	struct graphics_priv *(*overlay_new)(struct graphics_priv *gr, struct graphics_methods *meth, struct point *p, int w, int h, int wraparound);
+	/** @brief Load an image from a file.
+	 *
+	 * @param gr graphics object
+	 * @param meth output parameter for graphics methods object
+	 * @param path file name/path of image to load
+	 * @param w In: width to scale image to, or IMAGE_W_H_UNSET for original width.
+	 * Out: Actual width of returned image.
+	 * @param h heigth; see w
+	 * @param hot output parameter for image hotspot
+	 * @param rotate angle to rotate the image, in 90 degree steps (not supported by all plugins).
+	 * @return pointer to allocated image, to be freed by image_free()
+	 * @see image_free()
+	 */
 	struct graphics_image_priv *(*image_new)(struct graphics_priv *gr, struct graphics_image_methods *meth, char *path, int *w, int *h, struct point *hot, int rotation);
 	void *(*get_data)(struct graphics_priv *gr, const char *type);
 	void (*image_free)(struct graphics_priv *gr, struct graphics_image_priv *priv);
diff --git a/navit/graphics/android/graphics_android.c b/navit/graphics/android/graphics_android.c
index 696ee6b3c..2bfbacab4 100644
--- a/navit/graphics/android/graphics_android.c
+++ b/navit/graphics/android/graphics_android.c
@@ -246,9 +246,9 @@ image_new(struct graphics_priv *gra, struct graphics_image_methods *meth, char *
 	if (localBitmap) {
 		ret->width=(*jnienv)->CallIntMethod(jnienv, localBitmap, gra->Bitmap_getWidth);
 		ret->height=(*jnienv)->CallIntMethod(jnienv, localBitmap, gra->Bitmap_getHeight);
-		if((*w!=-1 && *w!=ret->width) || (*h!=-1 && *w!=ret->height)) {
+		if((*w!=IMAGE_W_H_UNSET && *w!=ret->width) || (*h!=IMAGE_W_H_UNSET && *w!=ret->height)) {
 			jclass scaledBitmap=(*jnienv)->CallStaticObjectMethod(jnienv, gra->BitmapClass, 
-				gra->Bitmap_createScaledBitmap, localBitmap, (*w==-1)?ret->width:*w, (*h==-1)?ret->height:*h, JNI_TRUE);
+				gra->Bitmap_createScaledBitmap, localBitmap, (*w==IMAGE_W_H_UNSET)?ret->width:*w, (*h==IMAGE_W_H_UNSET)?ret->height:*h, JNI_TRUE);
 			if(!scaledBitmap) {
 				dbg(lvl_error,"Bitmap scaling to %dx%d failed for %s",*w,*h,path);
 			} else {
diff --git a/navit/graphics/gtk_drawing_area/graphics_gtk_drawing_area.c b/navit/graphics/gtk_drawing_area/graphics_gtk_drawing_area.c
index 6ec67d1c0..9c7bdd511 100644
--- a/navit/graphics/gtk_drawing_area/graphics_gtk_drawing_area.c
+++ b/navit/graphics/gtk_drawing_area/graphics_gtk_drawing_area.c
@@ -205,7 +205,7 @@ image_new(struct graphics_priv *gr, struct graphics_image_methods *meth, char *n
 		GdkPixbufLoader *loader=gdk_pixbuf_loader_new();
 		if (!loader)
 			return NULL;
-		if (*w != -1 || *h != -1)
+		if (*w != IMAGE_W_H_UNSET || *h != IMAGE_W_H_UNSET)
 			gdk_pixbuf_loader_set_size(loader, *w, *h);
 		gdk_pixbuf_loader_write(loader, buffer->start, buffer->len, NULL);
 		gdk_pixbuf_loader_close(loader, NULL);
@@ -213,7 +213,7 @@ image_new(struct graphics_priv *gr, struct graphics_image_methods *meth, char *n
 		g_object_ref(pixbuf);
 		g_object_unref(loader);
 	} else {
-		if (*w == -1 && *h == -1)
+		if (*w == IMAGE_W_H_UNSET && *h == IMAGE_W_H_UNSET)
 			pixbuf=gdk_pixbuf_new_from_file(name, NULL);
 		else
 			pixbuf=gdk_pixbuf_new_from_file_at_size(name, *w, *h, NULL);
diff --git a/navit/graphics/opengl/graphics_opengl.c b/navit/graphics/opengl/graphics_opengl.c
index b6e0fb41a..c927299dc 100644
--- a/navit/graphics/opengl/graphics_opengl.c
+++ b/navit/graphics/opengl/graphics_opengl.c
@@ -451,7 +451,7 @@ image_new(struct graphics_priv *gr, struct graphics_image_methods *meth,
 		width = FreeImage_GetWidth(image);
 		height = FreeImage_GetHeight(image);
 
-		if ((*w != width || *h != height) && 0 < *w && 0 < *h) {
+		if ((*w != width || *h != height) && *w != IMAGE_W_H_UNSET && *h != IMAGE_W_H_UNSET) {
 			FIBITMAP *image2;
 			image2 = FreeImage_Rescale(image, *w, *h, FILTER_BOX);
 			FreeImage_Unload(image);
diff --git a/navit/graphics/win32/graphics_win32.c b/navit/graphics/win32/graphics_win32.c
index 124832a38..6ccf29564 100644
--- a/navit/graphics/win32/graphics_win32.c
+++ b/navit/graphics/win32/graphics_win32.c
@@ -1445,9 +1445,9 @@ static struct graphics_image_priv *image_new(struct graphics_priv *gr, struct gr
         /* Hash_key will be freed ater the hash table, so set it to NULL here to disable freing it on this function return */
         hash_key=NULL;
         if(ret) {
-            if (*w==-1)
+            if (*w==IMAGE_W_H_UNSET)
                 *w=ret->width;
-            if (*h==-1)
+            if (*h==IMAGE_W_H_UNSET)
                 *h=ret->height;
             if (*w!=ret->width || *h!=ret->height) {
                 if(ret->png_pixels && ret->hBitmap)