 January 2009, --Jcid

                              ------
                              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)

