home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / gfx / show / superview-lib / programmers / include / superview / svgfxbuffer.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-05-28  |  8.4 KB  |  229 lines
  1. /* superview/svgfxbuffer.h          */
  2. /* Version    : 11.3                */
  3. /* Date       : 30.04.1995          */
  4. /* Written by : Andreas R. Kleinert */
  5.  
  6. #ifndef SUPERVIEW_SVGFXBUFFER_H
  7. #define SUPERVIEW_SVGFXBUFFER_H
  8.  
  9. #ifndef SUPERVIEW_SUPERVIEW_H
  10. #include <superview/superview.h>
  11. #endif /* SUPERVIEW_SUPERVIEW_H */
  12.  
  13.  
  14. struct SV_GfxBuffer
  15. {
  16.  /* All pointers (e.g. svgfx_Buffer) have to be and are AllocVec()'ed
  17.     (as well as usually the structure itself).
  18.  
  19.     If you did not allocate SV_GfxBuffers by yourself, you must
  20.     neither free them nor do write-accesses to them.
  21.  
  22.     If you allocated them by yourself, you also have to free them
  23.     by yourself - if no one else is still accessing them.
  24.  */
  25.  
  26.  ULONG svgfx_Version;        /* structure version, see below                */
  27.  
  28.  ULONG svgfx_BufferType;     /* Data organization, see below                */
  29.  
  30.  ULONG svgfx_Width;          /* Graphic's Width                             */
  31.  ULONG svgfx_Height;         /* Graphic's Height                            */
  32.  ULONG svgfx_ColorDepth;     /* Graphic's ColorDepth                        */
  33.  ULONG svgfx_ViewMode32;     /* if NULL, best ScreenMode is suggested       */
  34.                              /* (results in LowRes, if not changed).        */
  35.  
  36.  UBYTE svgfx_Colors[256][3]; /* For ColorDepth <= 8 : 3-Byte RGB entries    */
  37.  
  38. /*
  39. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  40. begin of "case-dependent" entries
  41. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  42.  
  43.     ONLY if svgfx_BufferType == SVGFX_BUFFERTYPE_BITPLANE, else NULL.
  44.  
  45.     svgfx_BytesPerLine :
  46.  
  47.        size of one row
  48.        of a plane in Bytes
  49.      = Bytes per Row            : (( [width] +7)>>3)
  50.        Number of Rows per Plane : [height]
  51.        Number of Planes         : [depth]
  52.  
  53.  */
  54.  
  55.  ULONG svgfx_BytesPerLine; /* see above */
  56.  ULONG svgfx_PixelBits;    /* see below */
  57.  
  58. /*
  59.     ONLY if svgfx_BufferType == SVGFX_BUFFERTYPE_ONEPLANE, else NULL.
  60.  
  61.     svgfx_PixelBits    :
  62.  
  63.        Bits Per Pixel
  64.        (8, 16, 24, ...)
  65.     => Bytes per Row            : (svgfx_PixelBits>>3) * [width]
  66.        Number of Rows per Plane : [height]
  67.        Number of Planes         : ONE
  68.  
  69. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  70. end of "case-dependent" entries
  71. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  72.  */
  73.  
  74.  
  75.  APTR  svgfx_Buffer;         /* any kind of memory (no chip ram needed)     */
  76.  ULONG svgfx_BufferSize;     /* if you want to copy it ...                  */
  77.  
  78.  /* ----------------------------------------------------------------------- */
  79.  /* Begin of Version 2 entries: Check Version before reading further        */
  80.  /* ----------------------------------------------------------------------- */
  81.  
  82.  ULONG svgfx_NativeDIPF;     /* This one contains the DIPF_-Flags, which    */
  83.                              /* have been native to the original ViewMode   */
  84.                              /* of the graphics. So you may determine       */
  85.                              /* whether a graphics is HAM, EHB or such.     */
  86.                              /* May be NULL for non-Amiga sources.          */
  87.  
  88.  /* ----------------------------------------------------------------------- */
  89.  /* Size of structure may grow in future versions...                        */
  90.  /* ----------------------------------------------------------------------- */
  91. };
  92.  
  93. #define SVGFX_VERSION     (1)    /* this is the minimum              */
  94. #define SVGFX_ACT_VERSION (2)    /* this is the current max. version */
  95.  
  96.     /* When copying a GfxBuffer you usually refer to
  97.        sizeof(struct SV_GfxBuffer), which differs from version to version.
  98.        So you have to check, whether svgfx_Version is > SVGFX_ACT_VERSION.
  99.        If it is, just set svgfx_Version = SVGFX_ACT_VERSION, else
  100.        keep it untouched (or maybe set the version you need).
  101.     */
  102.  
  103. #define SVGFX_BUFFERTYPE_BITPLANE (1)  /* Amiga-like BitPlanes (unaligned)  */
  104. #define SVGFX_BUFFERTYPE_ONEPLANE (2)  /* single Byte-/Word-/24 Bit-Plane   */
  105.  
  106. /* there may be more types in the future */
  107. /* (at least reject all types > 2)       */
  108.  
  109.  
  110. /*
  111.    Some words about interpreting and using SV_GfxBuffer structures
  112.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  113.  
  114.    SVGFX_BUFFERTYPE_BITPLANE
  115.    =========================
  116.  
  117.    SVGFX_BUFFERTYPE_BITPLANE means, that there's plane stored after plane,
  118.    but _no padding_ of the lines is done (e.g. to word- or longword-
  119.    boundaries), which is different from Amiga-BPs or ACBM-ABITs :
  120.  
  121.          | line 1 of plane 1              | (each with svgfx_BytesPerLine)
  122.          | ...                            |
  123.          | line [height] of plane 1       |
  124.  
  125.                ...
  126.  
  127.          | line 1 of plane []             |
  128.          | ...                            |
  129.          | line [height] of plane []      |
  130.  
  131.                ...
  132.  
  133.          | line 1 of plane [depth]        |
  134.          | ...                            |
  135.          | line [height] of plane [depth] |
  136.  
  137.  
  138.    SVGFX_BUFFERTYPE_BITPLANE is only used upto 256 Colors at the time :
  139.    16 and 24 Bit data will usually not be stored this way.
  140.  
  141.  
  142.    SVGFX_BUFFERTYPE_ONEPLANE
  143.    =========================
  144.  
  145.    SVGFX_BUFFERTYPE_ONEPLANE means, that there's only one single plane stored.
  146.    The size of one pixel in this plane is defined in svgfx_PixelBits
  147.    (currently 8 for ChunkyPixel graphics or 24 for 24 Bit graphics).
  148.  
  149.          | line 1 with ([PixelBits] / 8) * [width] Bytes        |
  150.          | ...                                                  |
  151.          | line [height] with ([PixelBits] / 8) * [width] Bytes |
  152.  
  153.  
  154.    8 Bit  : Chunky Pixel (ColorMap) = 8       ; ColorRegister index
  155.    16 Bit : R:G:B                   = 5:5:5:1 ; + 1 Bit Alpha Channel : IGNORED
  156.    24 Bit : R:G:B                   = 8:8:8   ; RGB-value
  157.  
  158.  
  159.    So   8 Bit Data contains [width]   bytes in a row,
  160.        16 Bit Data contains [width]*2 bytes in a row
  161.    and 24 Bit Data contains [width]*3 bytes in a row.
  162.  
  163.    Currently you will not find any SV_GfxBuffers with 16 Bit data,
  164.    but this may change in the future.
  165.  
  166.  
  167.    Differences, which perhaps are not obviously
  168.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  169.  
  170.    In SV_GfxBuffer structures there are two "case-dependent" entries
  171.    (see structure definition of SV_GfxBuffer) :
  172.  
  173.    BITPLANE :   svgfx_BytesPerLine = ( [width] +7 )>>3
  174.                 svgfx_PixelBits    = 0;                   ** IGNORE IT
  175.                 svgfx_ColorDepth   = [number of planes]
  176.  
  177.    ONEPLANE :   svgfx_BytesPerLine = 0;                   ** IGNORE IT
  178.                 svgfx_PixelBits    = 8;                   ** or == 24
  179.                 svgfx_ColorDepth   = [used PixelBits]
  180.  
  181.  
  182.    svgfx_ColorDepth always describes the _real_ ColorDepth of the graphics,
  183.    which means the stored number of planes for BITPLANE data and the number
  184.    of _actually_ used pixelbits for ONEPLANE data.
  185.  
  186.    If svgfx_PixelBits is 24, svgfx_ColorDepth will perhaps always be 24, too.
  187.    But if svgfx_PixelBits is 8, it may be anything between 1 and 8.
  188.  
  189.    The reason is, that e.g. GIF pictures are always stored 8 Bit-wide,
  190.    no matter if they contain 4, 8 or 256 Colors.
  191.    This is just because these 8 Bit are simply a ColorRegister index
  192.    (into the field of RGB-Colors : svgfx_Colors).
  193.  
  194.    OK, there's no problem in displaying a ONEPLANE-8 graphics on a 256 Color
  195.    Screen, no matter which value svgfx_ColorDepth actually contains.
  196.    But if svgfx_ColorDepth is, let's say, only 4, this will be just a
  197.    waste of memory (and the last 256-16 = 240 colors will be black, anyway).
  198.  
  199.    So finally we can say, that the data in a ONEPLANE SV_GfxBuffer is just
  200.    stored the same way, as e.g. in ChunkyPixel modes of VGA-like Graphic Cards
  201.    or in the source-buffers for GfxLibs's WritePixelLine8().
  202.    (See "graphics.library"'s AutoDocs for more information on ChunkyPixel
  203.     buffer (PixelLine8) handling under V37-40 with ECS/AGA or RTG).
  204.  
  205.  
  206.    Which kind of data-storage is more likely ?
  207.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  208.    The way of data-storage only depend on the specific SVObject.
  209.  
  210.    Some Examples :
  211.  
  212.    FileType   BufferType     PixelBits    ColorDepth
  213.  
  214.    GIF        ONEPLANE       8            1..8
  215.    ILBM       BITPLANE       -            1..8
  216.    JPEG       ONEPLANE       8/24         8/24
  217.  
  218.  
  219.    So any program, which supports GfxBuffers should handle both formats.
  220.    This is not difficult, since superviewsupport.library
  221.    contains functions to convert ONEPLANE buffers into BITPLANE buffers
  222.    and vice versa.
  223.    So you actually only have to support one of the data-storage alternatives.
  224.  
  225.    (See Example-SourceCodes for more and detailed information !)
  226. */
  227.  
  228. #endif /* SUPERVIEW_SVGFXBUFFER_H */
  229.