image viewer: add quick guide describing how to add image decoder. also improve comments.

git-svn-id: svn://svn.rockbox.org/rockbox/trunk@29066 a1c6a512-1295-4272-9138-f99709370657

2 files changed, 50 insertions, 8 deletions

diff --git a/apps/plugins/imageviewer/imageviewer.h b/apps/plugins/imageviewer/imageviewer.h
index 504ef2bb3a..f35c1c7e6d 100644
--- a/apps/plugins/imageviewer/imageviewer.h
+++ b/apps/plugins/imageviewer/imageviewer.h
@@ -469,19 +469,24 @@ struct imgdec_api {
 
 /* functions need to be implemented in each image decoders. */
 struct image_decoder {
-    /* if unscaled image can be always displayed when there isn't enough memory
-     * for resized image. e.g. when using native format to store image. */
+    /* set true if unscaled image can be always displayed even when there isn't
+     * enough memory for resized image. e.g. when using native format to store
+     * image. */
     const bool unscaled_avail;
 
-    /* return needed size of buffer to store downscaled image by ds */
+    /* return needed size of buffer to store downscaled image by ds.
+     * this is used to calculate min downscale. */
     int (*img_mem)(int ds);
-    /* load image from filename. set width and height of info properly. also, set
-     * buf_size to remaining size of buf after load image. it is used to caluclate
-     * min downscale. */
+    /* load image from filename. use the passed buffer to store loaded, decoded
+     * or resized image later, so save it to local variables if needed.
+     * set width and height of info properly. also, set buf_size to remaining
+     * size of buf after load image. it is used to calculate min downscale.
+     * return PLUGIN_ERROR for error. ui will skip to next image. */
     int (*load_image)(char *filename, struct image_info *info,
                       unsigned char *buf, ssize_t *buf_size);
-    /* downscale loaded image by ds. note that buf to store reszied image is not
-     * provided. return PLUGIN_ERROR for error. ui will skip to next image. */
+    /* downscale loaded image by ds. use the buffer passed to load_image to
+     * reszie image and/or store resized image.
+     * return PLUGIN_ERROR for error. ui will skip to next image. */
     int (*get_image)(struct image_info *info, int ds);
     /* draw part of image */
     void (*draw_image_rect)(struct image_info *info,
diff --git a/apps/plugins/imageviewer/readme.txt b/apps/plugins/imageviewer/readme.txt
new file mode 100644
index 0000000000..b7ec71e7be
--- /dev/null
+++ b/apps/plugins/imageviewer/readme.txt
@@ -0,0 +1,37 @@
+this document describes how to add new image decoder.
+
+1. create a directory which name is your image decoder's name and put source files
+ under the directory.
+'const struct image_decoder image_decoder' and 'IMGDEC_HEADER' must be declared in
+ one of your source files.
+see imageviewer.h for the detail of struct image_decoder.
+
+2. add the directory name to apps/plugins/imageviewer/SUBDIR so that the decoder
+ is built.
+if the decoder is supported by particular targets, surround it with #if directive.
+e.g. if the decoder supports color LCD targets only,
+#ifdef HAVE_LCD_COLOR
+bmp
+#endif
+
+3. append appropriate entry to enum image_type in image_decoder.h, decoder_names
+ and ext_list in image_decoder.c so that the imageviewer plugin can recognize
+ the decoder.
+if the decoder is supported by particular targets, surround them with same #if
+ directive in SUBDIR.
+
+4. add entry to apps/plugins/viewers.config
+ (in format: file_extension,viewer/imageviewer) so that the file with specified 
+ file extension will be opened by image viewer plugin.
+if the decoder is supported by particular targets, surround it with same #if
+ directive in SUBDIR.
+
+5. add entry to apps/plugins/CATEGORIES (in format: decoder_name,viewer) so
+ that the build file is copied to viewers directory.
+DON'T surround this with #if directive.
+
+
+notes:
+if you need to use greylib functions to draw image, add the functions to
+ struct imgdec_api just like gray_bitmap_part because GREY_INFO_STRUCT is
+ declared in imageviewer and is not available from the decoder.