Split up user and developer documentation.

1 files changed, 129 insertions, 0 deletions

diff --git a/devdoc/Images.txt b/devdoc/Images.txt
new file mode 100644
index 00000000..62082e48
--- /dev/null
+++ b/devdoc/Images.txt
@@ -0,0 +1,129 @@
+ January 2009, --Jcid
+
+Update June 2015: See also doc/dw-images-and-backgrounds.doc, or
+../html/dw-images-and-backgrounds.html (generated by doxygen).
+
+                              ------
+                              IMAGES
+                              ------
+
+* When a image tag is found within a HTML page, Html_tag_open_img
+handles it by:
+
+   - Parsing & getting attribute values.
+   - Creating a new image structure (DilloImage) and its
+     associated widget (DwImage).
+     i.e. If 'Image' is the var for the structure, then
+          'Image->dw' is the widget.
+   - Requesting the image to be feeded by the cache.
+   - Sending some info to the browser interface.
+
+* The  cache  can  either request the image data from the net, or
+feed it directly from the dicache (decompressed image cache).
+
+*  Both  processes  are  somewhat different because the first one
+requires to decode the image data into RGB format, and the second
+one has the whole data already decoded.
+
+*  Regardless of the RGB-data feeding method, the decoded data is
+passed to the widget (DwImage) and drawn in a streamed way.
+   Note that INDEXED images are also decoded into RGB format.
+
+   Html_tag_open_img    // IMG element processing
+     Html_add_new_image // Read attributes, create image, add to HTML page
+       a_Image_new      // Create a 'DilloImage' data structure, to coordinate
+                        // decoded image-data transfer to an 'Imgbuf'.
+       Html_add_widget  // Adds the dw::Image to the page
+       Html_load_image  // Tells cache to retrieve image
+
+
+---------------------
+Fetching from the net
+---------------------
+
+*  a_Capi_open_url  initiates  the  resource  request,  and  when
+finally  the answer arrives, the HTTP header is examined for MIME
+type  and  either the GIF or PNG or JPEG decoder is set to handle
+the incoming data stream.
+
+   Decoding functions:
+     a_Gif_callback, a_Jpeg_callback and a_Png_callback.
+
+*  The  decoding  function calls the following dicache methods as
+the data is processed (listed in order):
+
+   a_Dicache_set_parms
+   a_Dicache_set_cmap (only for indexed-GIF images)
+   a_Dicache_write
+   a_Dicache_new_scan (MAY be called here or after set_cmap)
+   a_Dicache_close
+
+
+*  The  dicache  methods  call the necessary functions to connect
+with the widget code. This is done by calling image.c functions:
+
+   a_Image_set_parms
+   a_Image_set_cmap
+   a_Image_write
+   a_Image_new_scan
+   a_Image_close
+
+* The functions in image.c make the required Dw calls.
+
+
+-------------------------
+Fetching from the dicache
+-------------------------
+
+* a_Capi_open_url() tests the cache for the image, and the cache,
+via  a_Cache_open_url(), enqueues a client for it, without asking
+the  network  for the data. When the client queue is processed (a
+bit later), Dicache_image() is set as the callback.
+
+*  When  Dicache_image() is called, it sets the proper image data
+decoder  (RGB)  and its data structure based on the entry's Type.
+Then  it  substitutes  itself  with  a_Dicache_callback()  as the
+handling function, and gets out of the way.
+
+*  Thenceforth  the  rest  of  the  functions  calls is driven by
+a_Dicache_callback().
+
+
+-----------
+Misc. notes
+-----------
+
+*  Repeated images generate new cache clients, but they may share
+the  imgbuf.
+   Note:  Currently  there's  no  proper  support for transparent
+images  (i.e.  decode  to RGBA), but most of the time they render
+the  background  color  OK.  This is: when first loaded, repeated
+images  share  a  background  color,  but when cached they render
+correctly ;-). There's no point in trying to fix this because the
+correct  solution is to decode to RGBA and let the toolkit (FLTK)
+handle the transparency.
+
+*  The  first cache-client callback (Dicache_image()) is set when
+the Content-type of the image is got.
+
+*  Later  on,  when  there's a shared imgbuf, the dicache's logic
+avoids decoding it multiple times and reuses what's already done.
+
+*  The dicache-entry and the Image structure hold bit arrays that
+represent which rows have been decoded.
+
+* The image processing can be found in the following sources:
+
+  - image.{cc,hh}
+  - dicache.[ch]
+  - gif.[ch], png.[ch], jpeg.[ch]
+  - dw/image.{cc,hh}
+
+*  Bear  in  mind  that  there are four data structures for image
+code:
+
+  - DilloImage (image.hh)
+  - DICacheEntry (dicache.h)
+  - dw::Image (class Image in dw/image.hh)
+  - core::Imgbuf (imgbuf.hh)
+