home *** CD-ROM | disk | FTP | other *** search
/ Stars of Shareware: Programmierung / SOURCE.mdf / programm / msdos / c / xv221src / docs / info.old < prev    next >
Encoding:
Text File  |  1992-01-04  |  9.9 KB  |  201 lines
  1. Note:  This is pretty well obsolete, but may be of interest to any one who
  2. feels like hacking 'xv' 
  3.  
  4.    --jhb, 8/31/90
  5. ------------------------------------------------------------------------------
  6.  
  7.  
  8.   general concepts:
  9.  
  10.   1. main program should do command line parsing, call a LOAD routine of some
  11.      sort, and display the result.  It will sit in a loop parsing keyboard
  12.      commands until a file-changing command is given.
  13.  
  14.      Keyboard Commands:
  15.        Q:         quit
  16.        CR,SP:     next file
  17.        BS,DEL:    previous file
  18.        ,:         shrink picture 10%
  19.        .:         grow picture 10%
  20.        <:         shrink picture by factor of 2
  21.        >:         grow picture by factor of 2
  22.        N:         home.  (Show picture at normal size)
  23.        M:         max.   (grow picture to size of screen)
  24.        C:         crop picture
  25.        U:         uncrop picture
  26.        I:         info box
  27.        4:         4x3-ify the picture
  28.  
  29.      Mouse Commands:
  30.        Button1:  lets you draw a cropping rectangle
  31.        Button2:  
  32.        Button3:  
  33.  
  34.   2. LOAD routines:  given a file name.  They'll do optional suffix-tacking-on
  35.      if they wish to.  They will do whatever needs to be done to the picture
  36.      to get it into an 8-plane image with a colormap.  
  37.  
  38.      The load routines will return several things (in global variables):
  39.      pWIDE, pHIGH, a pWIDE*pHIGH array of pixels (pic) (one byte per), 0,0 is
  40.      the top-left corner of the image, a colormap (three 256-element arrays
  41.      of bytes, for r,g and b (called 'r', 'g', and 'b', oddly enough)
  42.  
  43.      load routines will return '0' if successful, a slew of non-zero things if
  44.      not 
  45.  
  46.   3. A common routine for colormap sort/compression (SortColormap()).
  47.      the colormap will be compressed.  That is, if only 37 colors
  48.      in the 256-element colormap are used, they will be the first 37 entries
  49.      in the colormap.  This way, the display portion of the code won't waste
  50.      resources allocating unused colors.  This routine will also modify the
  51.      PIC array accordingly.  
  52.  
  53.      This routine calculates 'numcols'.
  54.  
  55.      Thought:  have the colormap compression algorithm sort the colormap
  56.      so that the most-used color is first, and the other colors are in order
  57.      of decreasing distance from the first color.  (That is, the second color
  58.      will be the 'most unlike' the first color, the third color will be the
  59.      'second most unlike' the first color, and so on.)
  60.  
  61.      Justification:  Since we allocate colors in the order they're stored
  62.      in the colormap, it'd probably be better to get all the major colors
  63.      first, and then pick up the subtle shade differences if there's any
  64.      colors left.
  65.  
  66.      Improved sort algorithm.  Slower, but possibly more desirable.
  67.      (besides, the speed of this routine is not likely to be a problem)
  68.      Problem with previous algorithm:  a picture with a blue sky, a green
  69.      ground, and a dark blue car.  The previous algorithm will allocate the
  70.      sky blue (most used), and then try to allocate ALL THE SHADES OF GREEN
  71.      before trying for the dark blue.  Suboptimal.
  72.  
  73.      Solution, find the most used color, put it first in the cmap.
  74.      find the color the greatest distance from that, put it second in the cmap
  75.      NOW, find the color that is farthest away from BOTH of those colors
  76.      (that is, for each color left in the cmap, compute the min of it's 
  77.      distances from the ones that have been allocated already.  Then, take the
  78.      one that's got the largest min distance and allocate it.  continue)
  79.  
  80.      Still more modification to sort algorithm: The modified algorithm 
  81.      described above is a good thing, but runs on the order O(3).  Practical
  82.      upshot is that doing it for all 256 colors in a picture takes far too
  83.      long.  New idea: run that algorithm for the first 32 colors (an
  84.      arbitrary smallish number, and plenty fast), then sort the remaining 
  85.      colors in order of decreasing use.
  86.  
  87.   4. A common routine for 24-bit RGB -> 8 bit colormap conversion.
  88.      Since several different data formats might want to do this, this
  89.      routine will exist for their calling pleasure.  Input will be a wide*high
  90.      * 3 byte array of pixels, 3 bytes per (in order R, G, and B).  The
  91.      procedure will do the 'thing' and store results in all the global
  92.      variables that the load routines are supposed to return.  A load routine
  93.      should be able to just call this routine (once it's built the 24-bit
  94.      image) and return.  
  95.  
  96.      Input will also be number of colors to use.  That is, while it will still
  97.      produce a 8-bit PIC array, you might want it to only use 16 colors,
  98.      rather than 256.  (Say, if you're on a 4 bit display).  The reason you'd
  99.      want it to do this is that it'll probably do a better job of creating a
  100.      16-color picture than the DISPLAY routine would (if it was handed a 256
  101.      color picture and asked to display it on a 16-color display).
  102.      
  103.      The 24to8 routine (Conv24to8) will be clever, and if it knows you're
  104.      displaying on a monochrome screen (or -mono is set) or that you're
  105.      displaying on a 1-bit display (or -nc 0), it will just return an
  106.      8-bit greyscale version of the picture.  This is because running the
  107.      full 24-bit RGB to 8-bit pseudocolor conversion takes a long time,
  108.      and shouldn't be done if not necessary.
  109.  
  110.   5. Display routines.  Do whatever is necessary to show PIC on display.
  111.      This includes things like building an Ximage in the correct depth,
  112.      expanding/compressing size of image
  113.  
  114.      There will be a AllocColors() routine that will take the desired colormap
  115.      and see what it can do, based on the type of display you're using.
  116.      This routine will be called once per picture, before doing Resize()
  117.      (As Resize() calls CreateXImage()...)
  118.      
  119.      if (based on 'theVisual', or '-mono') we appear to be running on a 
  120.      GrayScale or StaticGray display, this algorithm will FIRST run through
  121.      the desired colormap (the 'epic' colormap) and replace the r,g,b values
  122.      for each entry with the corresponding intensity value (I=(.3r+.5g+.2b)/3)
  123.      This way, pictures will be correctly displayed on mono screens.
  124.  
  125.      Algorithm:  for >1 bit displays (ie, greyscale/color), alloc colors in
  126.      the X colormap in the order that the SortColormap routine returned.
  127.      Colors that couldn't be allocated are matched to the closest colors in
  128.      the global X colormap, or the just the colors allocated (based on the
  129.      value of 'noglob')
  130.  
  131.      the 'cols[]' array will hold the mapping between 'epic' colors and X
  132.      colors.  (ie, color #37 in epic and the epic colormap will correspond to 
  133.      color # cols[37] in the X image and the X colormap)
  134.  
  135.      the 'freecols[]' array (and nfcols, the length of it) will hold the X
  136.      pixel values of the colors that were allocated, so that they may be
  137.      later un-allocated.  Also, it will NOT have duplicate entries in it.
  138.      (ie, if allocating (15,15,15) and (16,16,16) both return pixel #2,
  139.      pixel #2 will be in freecols ONCE.)
  140.  
  141.      More algorithm:  for 1 bit displays there's only going to be two
  142.      colors, 'black' and 'white'.  (What the two colors actually look like
  143.      on the screen (ie, maybe it's blue and white, or black and green), is
  144.      not important.  So what we do here is, rather than try to allocate any
  145.      colors (it'd probably fail anyhow), run the Floyd Steinberg dithering
  146.      algorithm over the picture, and just use 'black' and 'white'
  147.  
  148.   6. There's several variables that seem to do the same thing.  They don't.
  149.      Here's what they do:
  150.  
  151.        pic, pWIDE, pHIGH:   This is the 8-bit image ret. by the load routine
  152.  
  153.        cpic, cWIDE, cHIGH,
  154.        cXOFF, cYOFF:        This is the cropped version of pic.  If there is
  155.                             no cropping going on, it will point to pic.
  156.                 cXOFF and cYOFF specify the offset from 0,0 of 
  157.                 the original pic.  (ie, pixel cXOFF,cYOFF in the
  158.                 original picture will be at 0,0 in the cpic image
  159.  
  160.        epic, eWIDE, eHIGH:  This is another 8-bit image.  This is an expanded/
  161.                             compressed version of cpic.  Generated in the
  162.                 Resize() function.  When there is no expansion
  163.                 (ie, eWIDE=pWIDE, eHIGH=pHIGH) epic *will* point
  164.                 to 'cpic'.  This way the X conversion routines
  165.                 can simply use epic, eWIDE, and eHIGH.
  166.  
  167.        theImage:  This is an Ximage version of epic.  It'll be in whatever
  168.                   depth/format is deemed appropriate for the X display.
  169.           It is generated from epic after epic has been Resize()'d
  170.           It's generated in the function CreateXImage()
  171.  
  172.      What happens to a picture from loading to display:
  173.        picture is loaded in some native format  
  174.            (local to LOAD routine)
  175.        picture is converted to 8-bit colortable routine  (pic)
  176.            (in LOAD routine.  native format data is thrown away)
  177.        LOOP
  178.          'pic' is cropped, if desired.  cpic points to picture data
  179.      'cpic' is expanded, if desired.  epic points to data
  180.      'epic' is converted to theImage 
  181.              (an X Format in the depth of the screen)
  182.        REPEAT
  183.  
  184.  
  185.   7. It should be noted that the several functions break on machines where
  186.      'int' is <32 bits.  These machines are wrong.
  187.  
  188.   8. added a 'perfect' mode, where it installs it's own colormap
  189.  
  190.   9. further thoughts...
  191.      add an ability to display multiple iconified-files at once (has to
  192.      be done in 'mono' mode... (contact sheets, Hagan calls them)
  193.  
  194.  10. color usage.  six colors can be specified via command-line/resource
  195.      database.  They are white,black, foreground,background, and 
  196.      info.foreground,info.background.  white and black are only used in
  197.      the 1-bit dithering routines (FloydDitherize8 and FloydDitherize1)
  198.  
  199.      foreground,background specify the colors of the window/frame
  200.      info.{fore,back}ground specifies the colors of the info box 
  201.