# HG changeset patch
# User Thinker K.F. Li <thinker@branda.to>
# Date 1232780943 -28800
# Node ID b42ee279669edd6471f76d2536dd9497648369b9
# Parent  1ed06481e9ea0217b72943e7f0ccfa8d5b558da9
Change function name and add comments.
- sh_image_set_geometry() to replace sh_image_set().
- page "Image and Image Loader".
- comments.

diff -r 1ed06481e9ea img/image_n_ldr.dia
Binary file img/image_n_ldr.dia has changed
diff -r 1ed06481e9ea img/image_n_ldr.png
Binary file img/image_n_ldr.png has changed

diff -r 1ed06481e9ea -r b42ee279669e img/image_n_ldr.dia
Binary file img/image_n_ldr.dia has changed
diff -r 1ed06481e9ea -r b42ee279669e img/image_n_ldr.png
Binary file img/image_n_ldr.png has changed
diff -r 1ed06481e9ea -r b42ee279669e include/mb_redraw_man.h
--- a/include/mb_redraw_man.h	Fri Jan 23 23:22:14 2009 +0800
+++ b/include/mb_redraw_man.h	Sat Jan 24 15:09:03 2009 +0800
@@ -196,6 +196,8 @@
     DARRAY_CLEAN(rdman_get_gen_geos(rdman))
 #define rdman_prop_store(rdman) ((rdman)->props)
 #define rdman_img_ldr(rdman) ((rdman)->img_ldr)
+#define rdman_set_img_ldr(rdman, ldr)		\
+    do { (rdman)->img_ldr = ldr; } while(0)
 
 /*! \brief Attach backend to the redraw manager so that we can hide the backend from the users.
  *
diff -r 1ed06481e9ea -r b42ee279669e include/mb_shapes.h
--- a/include/mb_shapes.h	Fri Jan 23 23:22:14 2009 +0800
+++ b/include/mb_shapes.h	Sat Jan 24 15:09:03 2009 +0800
@@ -89,8 +89,8 @@
 				      co_aix w, co_aix h);
 extern void sh_image_transform(shape_t *shape);
 extern void sh_image_draw(shape_t *shape, cairo_t *cr);
-extern void sh_image_set(shape_t *shape, co_aix x, co_aix y,
-			 co_aix w, co_aix h);
+extern void sh_image_set_geometry(shape_t *shape, co_aix x, co_aix y,
+				  co_aix w, co_aix h);
 /* @} */
 /* @} */
 
diff -r 1ed06481e9ea -r b42ee279669e src/X_supp.c
--- a/src/X_supp.c	Fri Jan 23 23:22:14 2009 +0800
+++ b/src/X_supp.c	Sat Jan 24 15:09:03 2009 +0800
@@ -420,6 +420,8 @@
  */
 static int X_MB_init(const char *display_name,
 	      int w, int h, X_MB_runtime_t *xmb_rt) {
+    mb_img_ldr_t *img_ldr;
+    
     memset(xmb_rt, 0, sizeof(X_MB_runtime_t));
 
     xmb_rt->w = w;
@@ -450,8 +452,9 @@
 
     xmb_rt->tman = mb_tman_new();
 
-    xmb_rt->img_ldr = simple_mb_img_ldr_new("./");
-    xmb_rt->rdman->img_ldr = xmb_rt->img_ldr;
+    img_ldr = simple_mb_img_ldr_new("./");
+    xmb_rt->img_ldr = img_ldr;
+    rdman_set_img_ldr(xmb_rt->rdman, img_ldr);
     
 #ifndef ONLY_MOUSE_MOVE_RAW
     xmb_rt->last = NULL;
diff -r 1ed06481e9ea -r b42ee279669e src/paint.c
--- a/src/paint.c	Fri Jan 23 23:22:14 2009 +0800
+++ b/src/paint.c	Sat Jan 24 15:09:03 2009 +0800
@@ -245,6 +245,10 @@
 }
 
 
+/*! \brief Using an image as a paint.
+ *
+ * This type of paints fill/stroke shapes with an image.
+ */
 typedef struct _paint_image {
     paint_t paint;
     mb_img_data_t *img;
@@ -273,6 +277,10 @@
     free(paint);
 }
 
+/*! \brief Create an image painter.
+ *
+ * Create a painter that fill/stroke shapes with an image.
+ */
 paint_t *rdman_paint_image_new(redraw_man_t *rdman,
 			       mb_img_data_t *img) {
     paint_image_t *paint;
@@ -323,6 +331,12 @@
     return (paint_t *)paint;
 }
 
+/*! \brief Setting transformation from user space to image space.
+ *
+ * This transformation matrix maps points drawed in user space to
+ * corresponding points in image space.  It is used to resample
+ * the image to generate pixels of result image.
+ */
 void paint_image_set_matrix(paint_t *paint, co_aix matrix[6]) {
     paint_image_t *img_paint = (paint_image_t *)paint;
     cairo_matrix_t cmatrix;
diff -r 1ed06481e9ea -r b42ee279669e src/shape_image.c
--- a/src/shape_image.c	Fri Jan 23 23:22:14 2009 +0800
+++ b/src/shape_image.c	Sat Jan 24 15:09:03 2009 +0800
@@ -6,10 +6,51 @@
 #include "mb_img_ldr.h"
 #include "mb_tools.h"
 
+/*! \page sh_image_n_image_ldr Image and Image Loader
+ *
+ * Image (\ref sh_image_t) is a shape to show an image on the output
+ * device.  Programmers manipulate object of an image shape to show it
+ * at specified position with specified size.  To create a new instance
+ * of sh_iamge_t, an image should be specified.  Programmers must have
+ * a way to load image from files.  The solution proposed by MadButterfly
+ * is image loader (\ref mb_img_ldr_t).
+ *
+ * Image loader is a repository of image files, programmers give him an
+ * ID and get an image returned the loader.  Image loader decodes image
+ * files specified IDs and return them in an internal representation.
+ * The internal representation of an array of pixels.  Pixels are in
+ * order of columns (X-axis) and then row by row (Y-axis).  An pixel
+ * can be 32bits, for ARGB, 24bits, for RGB, 8bits, for 8bits Alpha or
+ * 256-grey-levels, and 1bits, for bitmap.
+ *
+ * Every row is padded to round to byte boundary, a rounded row is a stride.
+ * Bytes a stride occupied is stride size.  The internal rpresentation
+ * is a series of strides.  The data returned by image loader is
+ * \ref mb_img_data_t type.  mb_img_data_t::content is data in internal
+ * representation.
+ *
+ * \ref simple_mb_img_ldr_t is a simple implementation of image loader.
+ * It is a repository of image files in a directory and sub-directories.
+ * ID of an image is mapped to a file in the directory and sub-directories.
+ * ID it-self is a relative path relate to root directory of the repository.
+ * \ref simple_mb_img_ldr_t handle PNG files only, now.
+ *
+ * \section get_img_ldr Get an Image Loader for Program
+ * redraw_man_t::img_ldr is an image loader assigned by backend.
+ * X backend, now, create an instance of simple_mb_img_ldr_t and assigns
+ * the instance to redraw_man_t::img_ldr.  Programmers should get
+ * image loader assigned for a rdman by calling rdman_img_ldr().
+ *
+ * \image html image_n_ldr.png
+ *
+ */
+
 #define ASSERT(x)
 #define OK 0
 #define ERR -1
 
+/*! \brief Image shape.
+ */
 typedef struct _sh_image {
     shape_t shape;
     
@@ -84,6 +125,7 @@
     for(i = 0; i < 4; i++)
 	coord_trans_pos(img->shape.coord, &poses[i][0], &poses[i][1]);
 
+    /* Transformation from user space to image space */
     img_matrix[0] = (poses[1][0] - poses[0][0]) / img->w;
     img_matrix[1] = (poses[1][1] - poses[0][1]) / img->w;
     img_matrix[2] = -poses[0][0];
@@ -112,8 +154,12 @@
     cairo_close_path(cr);
 }
 
-void sh_image_set(shape_t *shape, co_aix x, co_aix y,
-		  co_aix w, co_aix h) {
+/*! \brief Change geometry of an image.
+ *
+ * Set position and size of an image.
+ */
+void sh_image_set_geometry(shape_t *shape, co_aix x, co_aix y,
+			   co_aix w, co_aix h) {
     sh_image_t *img = (sh_image_t *)shape;
 
     img->x = x;