home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / cd32 / cd32_support / doc / writechunkypixels.doc < prev    next >
Text File  |  1993-10-18  |  4KB  |  87 lines
  1. For your convenience, the autodoc for the new V40 WriteChunkyPixels
  2. function is attached below.  All CD32 developers should have the full
  3. V40 OS for their development machine, and V40 autodocs, includes,
  4. libs, and fd's.  Archives of the V40 Workbench disks, V40 kickfiles,
  5. and V40 development files may be downloaded from our closed
  6. developer conferences on BIX (US), ADSP (Europe), and CIX (UK).
  7.  
  8. graphics.library/WriteChunkyPixels         graphics.library/WriteChunkyPixels
  9.  
  10.    NAME
  11.     WriteChunkyPixels -- write the pen number value of a rectangular array
  12.     of pixels starting at a specified x,y location and continuing
  13.     through to another x,y location within a certain RastPort. (V40)
  14.  
  15.    SYNOPSIS
  16.     WriteChunkyPixels(rp,xstart,ystart,xstop,ystop,array,bytesperrow)
  17.                       A0 D0     D1     D2    D3    A2     D4
  18.  
  19.     VOID WriteChunkyPixels(struct  RastPort *, LONG, LONG,
  20.          LONG, LONG, UBYTE *, LONG);
  21.  
  22.    FUNCTION
  23.     For each pixel in a rectangular region, decode the pen number selector
  24.     from a linear array of pen numbers into the bit-planes used to describe
  25.     a particular rastport.
  26.  
  27.    INPUTS
  28.     rp     -  pointer to a RastPort structure
  29.     (xstart,ystart) -  starting point in the RastPort
  30.     (xstop,ystop)   -  stopping point in the RastPort
  31.     array  - pointer to an array of UBYTEs from which to fetch the
  32.              pixel data.
  33.     bytesperrow - The number of bytes per row in the source array.
  34.         This should be at least as large as the number of pixels
  35.         being written per line.
  36.  
  37.    RESULT
  38.  
  39.    NOTE
  40.     xstop must be >= xstart
  41.     ystop must be >= ystart
  42.     The source array can be in fast RAM.
  43.  
  44.    ===chunky-to-planar conversion HW:
  45.  
  46.    GfxBase->ChunkyToPlanarPtr is either NULL, or a pointer to a HW
  47.    register used to aid in the process of converting 8-bit chunky 
  48.    pixel data into the bit-plane format used by the Amiga custom
  49.    display chips. If NULL, then such hardware is not present.
  50.  
  51.    If an expansion device provides hardware which operates compatibly,
  52.    than it can install the HW address into this pointer at boot time,
  53.    and the system will use it.
  54.  
  55.    This pointer may be used for direct access to the chunky-to-planar
  56.    conversion HW, if more is desired than the straight chunky-pixel
  57.    copy that is performed by WriteChunkyPixels().
  58.  
  59.    If using the hardware directly, it should only be accessed when
  60.    the task using it has control of the blitter (via OwnBlitter()),
  61.    since this is the locking used to arbitrate usage of this device.
  62.  
  63.    The hardware may be viewed as a device which accepts 32 8-bit
  64.    chunky pixels and outputs 8 longwords of bitplane data.
  65.  
  66.    For proper operation, exactly 8 longwords (containing 32 pixels)
  67.    of chunky data should be written to *(GfxBase->ChunkyToPlanarPtr).
  68.    After the data is written, bitplane data (starting with plane 0)
  69.    can be read back a longword at a time. There is no need to read
  70.    back all 8 longwords if the high-order bitplanes are not needed.
  71.  
  72.    Since WriteChunkyPixels is not (currently) particularly fast on 
  73.    systems without the chunky-to-planar hardware, time critical
  74.    applications (games, etc) may want to use their own custom conversion
  75.    routine if GfxBase->ChunkyToPlanarPtr is NULL, and call
  76.    WriteChunkyPixels() otherwise.
  77.  
  78.    This pointer is only present in GfxBase in versions of graphics.library
  79.    >= 40, so this should be checked before the pointer is read.
  80.  
  81.    BUGS
  82.     Not very fast on systems without chunky-to-planar conversion
  83.     hardware.
  84.  
  85.    SEE ALSO
  86.     WritePixel()  graphics/rastport.h
  87.