home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / GFX / viewer / SVLIBS81.LHA / superview-lib / Programmers / include / superview / superview.h next >
Encoding:
C/C++ Source or Header  |  1994-08-13  |  11.5 KB  |  358 lines
  1. /* superview/superview.h        */
  2. /* Version    : 7.1            */
  3. /* Date       : 16.07.1994        */
  4. /* Written by : Andreas R. Kleinert */
  5.  
  6. #ifndef SUPERVIEW_SUPERVIEW_H
  7. #define SUPERVIEW_SUPERVIEW_H
  8.  
  9.  
  10. /* *************************************************** */
  11. /* *                             * */
  12. /* * Version Defines                     * */
  13. /* *                             * */
  14. /* *************************************************** */
  15.  
  16. #define SVLIB_VERSION  7
  17.  
  18.  
  19. /* *************************************************** */
  20. /* *                             * */
  21. /* * Includes                         * */
  22. /* *                             * */
  23. /* *************************************************** */
  24.  
  25. #ifndef EXEC_TYPES_H
  26. #include <exec/types.h>
  27. #endif /* EXEC_TYPES_H */
  28.  
  29. #ifndef LIBRARIES_DOS_H
  30. #include <libraries/dos.h>
  31. #endif /* LIBRARIES_DOS_H */
  32.  
  33. #ifndef _STDIO_H
  34. #include <stdio.h>
  35. #endif /* _STDIO_H */
  36.  
  37. #ifndef _STDLIB_H
  38. #include <stdlib.h>
  39. #endif /* _STDLIB_H */
  40.  
  41. #ifndef _STRING_H
  42. #include <string.h>
  43. #endif /* _STRING_H */
  44.  
  45. #ifndef SUPERVIEW_SVINFO_H
  46. #include <superview/svinfo.h>
  47. #endif /* SUPERVIEW_SVINFO_H */
  48.  
  49.  
  50. /* *************************************************** */
  51. /* *                             * */
  52. /* * Custom Defines                     * */
  53. /* *                             * */
  54. /* *************************************************** */
  55.  
  56. #ifndef N
  57. #define N NULL     /* useful */
  58. #endif /* N */
  59.  
  60.  
  61. /* *************************************************** */
  62. /* *                             * */
  63. /* * MACROs for Version-Tests                 * */
  64. /* *                             * */
  65. /* *************************************************** */
  66.  
  67. #define LibVer(x) ( ((struct Library *) x)->lib_Version )
  68. #define OS_VER      LibVer(SysBase)
  69.  
  70.  
  71. /* *************************************************** */
  72. /* *                             * */
  73. /* * DEFINES                         * */
  74. /* *                             * */
  75. /* *************************************************** */
  76.  
  77.  
  78. /* Possible FileTypes */
  79.  
  80. #define SV_FILETYPE_NONE     ((ULONG) 0)
  81. #define SV_FILETYPE_UNKNOWN  SV_FILETYPE_NONE
  82. #define SV_FILETYPE_ILLEGAL  ((ULONG) 0xFFFFFFFF)
  83.  
  84. #define SV_FILETYPE_ILBM     ((ULONG) 1)          /* IFF-ILBM, any derivat   */
  85. #define SV_FILETYPE_ACBM     ((ULONG) 2)          /* IFF-ACBM, any derivat   */
  86. #define SV_FILETYPE_DATATYPE ((ULONG) 3)          /* V39-Datatype-Object     */
  87.  
  88.      /*
  89.     up to here  : Constant codes for IFF-ILBM, IFF-ACBM and DataTypes
  90.               (constant for compatibility reasons).
  91.     above these : External, user defined FileSubTypes
  92.               (defined EACH TIME NEW at Library's startup-time).
  93.      */
  94.  
  95.  
  96. /* Possible SubTypes of FileTypes */
  97.  
  98. #define SV_SUBTYPE_NONE     ((ULONG) 0)
  99. #define SV_SUBTYPE_UNKNOWN  SV_SUBTYPE_NONE
  100. #define SV_SUBTYPE_ILLEGAL  ((ULONG) 0xFFFFFFFF)
  101.  
  102. #define SV_SUBTYPE_ILBM     ((ULONG) 1)          /* Is IFF-ILBM              */
  103. #define SV_SUBTYPE_ILBM_01  ((ULONG) 2)          /* Is IFF-ILBM, CmpByteRun1 */
  104. #define SV_SUBTYPE_ACBM     ((ULONG) 3)          /* Is IFF-ACBM              */
  105. #define SV_SUBTYPE_DATATYPE ((ULONG) 4)          /* Is V39-DataType-Object   */
  106.  
  107.      /*
  108.     up to here  : Constant codes for IFF-ILBM, IFF-ACBM and DataTypes
  109.               (constant for compatibility reasons).
  110.     above these : External, user defined FileSubTypes
  111.               (defined EACH TIME NEW at Library's startup-time).
  112.      */
  113.  
  114.  
  115. /* Possible Input and Output mediums */
  116.  
  117. #define AKO_MEDIUM_NONE     ((ULONG) 0)          /* means : DEFAULT          */
  118. #define AKO_MEDIUM_ILLEGAL  ((ULONG) 0xFFFFFFFF)
  119.  
  120. #define AKO_MEDIUM_DISK ((ULONG) 1)              /* Read and Write media     */
  121. #define AKO_MEDIUM_CLIP ((ULONG) 2)
  122.  
  123.      /* not any medium might be supported by any SVObject */
  124.  
  125.  
  126. /* *************************************************** */
  127. /* *                             * */
  128. /* * Function Error Codes                 * */
  129. /* *                             * */
  130. /* *************************************************** */
  131.  
  132. #define SVERR_MAX_ERROR_TEXT_LENGTH (80)       /* plus Null-Byte */
  133.  
  134. #define SVERR_NO_ERROR             (NULL)
  135. #define SVERR_INTERNAL_ERROR         ((ULONG) 0xFFFFFFFF)
  136.  
  137. #define SVERR_UNKNOWN_FILE_FORMAT    ((ULONG) 1)
  138. #define SVERR_FILE_NOT_FOUND         ((ULONG) 2)
  139. #define SVERR_NO_MEMORY          ((ULONG) 3)
  140. #define SVERR_IFFPARSE_ERROR         ((ULONG) 4)
  141. #define SVERR_NO_CLIPBOARD         ((ULONG) 5)
  142. #define SVERR_NO_SCREEN          ((ULONG) 6)
  143. #define SVERR_NO_FILE             ((ULONG) 7)
  144. #define SVERR_NO_HANDLE          ((ULONG) 8)
  145. #define SVERR_NO_DATA             ((ULONG) 9)
  146. #define SVERR_GOT_NO_WINDOW         ((ULONG) 10)
  147. #define SVERR_GOT_NO_SCREEN         ((ULONG) 11)
  148. #define SVERR_NO_INFORMATION         ((ULONG) 12)
  149. #define SVERR_ILLEGAL_ACCESS         ((ULONG) 13)
  150. #define SVERR_DECODE_ERROR         ((ULONG) 14)
  151. #define SVERR_UNKNOWN_PARAMETERS     ((ULONG) 15)
  152. #define SVERR_ACTION_NOT_SUPPORTED   ((ULONG) 16)
  153. #define SVERR_VERSION_CONFLICT         ((ULONG) 17)
  154. #define SVERR_NO_DRIVER_AVAILABLE    ((ULONG) 18)
  155.  
  156.     /* Each new Library-Subversion may contain new Codes above
  157.        the last one of these.
  158.        So do not interpret the codes directly, but use
  159.        SVL_GetErrorString().
  160.        Maybe, newer Codes will not be listed up here.
  161.     */
  162.  
  163. struct SV_GfxBuffer
  164. {
  165.  /* All pointers (e.g. svgfx_Buffer) have to be and are AllocVec()'ed.
  166.  
  167.     If you did not allocate SV_GfxBuffers by yourself, you must
  168.     neither free them nor do write-accesses to them.
  169.  
  170.     If you allocated them by yourself, you also have to free them
  171.     by yourself - if no one else is still accessing them.
  172.  */
  173.  
  174.  ULONG svgfx_Version;         /* structure version, see below            */
  175.  
  176.  ULONG svgfx_BufferType;     /* Data organization, see below            */
  177.  
  178.  ULONG svgfx_Width;         /* Graphic's Width                             */
  179.  ULONG svgfx_Height;         /* Graphic's Height                            */
  180.  ULONG svgfx_ColorDepth;     /* Graphic's ColorDepth                        */
  181.  ULONG svgfx_ViewMode32;     /* if NULL, best ScreenMode is suggested        */
  182.                              /* (results in LowRes, if not changed).         */
  183.  
  184.  UBYTE svgfx_Colors[256][3]; /* For ColorDepth <= 8 : 3-Byte RGB entries    */
  185.  
  186. /*
  187. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  188. begin of "case-dependent" entries 
  189. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  190.  
  191.     ONLY if svgfx_BufferType == SVGFX_BUFFERTYPE_BITPLANE, else NULL.
  192.  
  193.     svgfx_BytesPerLine :
  194.  
  195.        size of one row
  196.        of a plane in Bytes
  197.      = Bytes per Row            : (( [width] +7)>>3)
  198.        Number of Rows per Plane : [height]
  199.        Number of Planes         : [depth]
  200.  
  201.  */
  202.  
  203.  ULONG svgfx_BytesPerLine; /* see above */
  204.  ULONG svgfx_PixelBits;    /* see below */
  205.  
  206. /*
  207.     ONLY if svgfx_BufferType == SVGFX_BUFFERTYPE_ONEPLANE, else NULL.
  208.  
  209.     svgfx_PixelBits    :
  210.  
  211.        Bits Per Pixel
  212.        (8, 16, 24, ...)
  213.     => Bytes per Row            : (svgfx_PixelBits>>3) * [width]
  214.        Number of Rows per Plane : [height]
  215.        Number of Planes         : ONE
  216.  
  217. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  218. end of "case-dependent" entries 
  219. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  220.  */
  221.  
  222.  
  223.  APTR  svgfx_Buffer;         /* any kind of memory (no chip ram needed)     */
  224.  ULONG svgfx_BufferSize;     /* if you want to copy it ...            */
  225.  
  226.  
  227.  /* size of structure may grow in future versions : Check svgfx_Version ! */
  228. };
  229.  
  230. #define SVGFX_VERSION (1)
  231.  
  232. #define SVGFX_BUFFERTYPE_BITPLANE (1)  /* Amiga-like BitPlanes            */
  233. #define SVGFX_BUFFERTYPE_ONEPLANE (2)  /* single Byte-/Word-/24 Bit-Plane */
  234.  
  235. /* there may be more types in the future */
  236. /* (at least reject all types > 2)       */
  237.  
  238.  
  239. /*
  240.    Some words about interpreting and using SV_GfxBuffer structures
  241.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  242.  
  243.    SVGFX_BUFFERTYPE_BITPLANE
  244.    =========================
  245.  
  246.    SVGFX_BUFFERTYPE_BITPLANE means, that there's plane stored after plane,
  247.    but _no padding_ of the lines is done (e.g. to word- or longword-
  248.    boundaries), which is different from Amiga-BPs or ACBM-ABITs :
  249.  
  250.          | line 1 of plane 1              | (each with svgfx_BytesPerLine)
  251.          | ...                            |
  252.          | line [height] of plane 1       |
  253.  
  254.                ...
  255.  
  256.          | line 1 of plane []             |
  257.          | ...                            |
  258.          | line [height] of plane []      |
  259.  
  260.                ...
  261.  
  262.          | line 1 of plane [depth]        |
  263.          | ...                            |
  264.          | line [height] of plane [depth] |
  265.  
  266.  
  267.    SVGFX_BUFFERTYPE_BITPLANE is only used upto 256 Colors at the time :
  268.    16 and 24 Bit data will usually not be stored this way.
  269.  
  270.  
  271.    SVGFX_BUFFERTYPE_ONEPLANE
  272.    =========================
  273.  
  274.    SVGFX_BUFFERTYPE_ONEPLANE means, that there's only one single plane stored.
  275.    The size of one pixel in this plane is defined in svgfx_PixelBits
  276.    (currently 8 for ChunkyPixel graphics or 24 for 24 Bit graphics).
  277.  
  278.          | line 1 with ([PixelBits] / 8) * [width] Bytes        |
  279.          | ...                                                  |
  280.          | line [height] with ([PixelBits] / 8) * [width] Bytes |
  281.  
  282.  
  283.    8 Bit  : Chunky Pixel (ColorMap) = 8       ; ColorRegister index
  284.    16 Bit : R:G:B                   = 5:5:5:1 ; + 1 Bit Alpha Channel : IGNORED
  285.    24 Bit : R:G:B                   = 8:8:8   ; RGB-value
  286.  
  287.  
  288.    So   8 Bit Data contains [height]   bytes in a row,
  289.        16 Bit Data contains [height]*2 bytes in a row
  290.    and 24 Bit Data contains [height]*3 bytes in a row.
  291.  
  292.    Currently you will not find any SV_GfxBuffers with 16 Bit data,
  293.    but this may change in the future.
  294.  
  295.  
  296.    Differences, which perhaps are not obviously
  297.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  298.  
  299.    In SV_GfxBuffer structures there are two "case-dependent" entries
  300.    (see structure definition of SV_GfxBuffer) :
  301.    
  302.    BITPLANE :   svgfx_BytesPerLine = ( [width] +7 )>>3
  303.                 svgfx_PixelBits    = 0;                   ** IGNORE IT
  304.                 svgfx_ColorDepth   = [number of planes]
  305.  
  306.    ONEPLANE :   svgfx_BytesPerLine = 0;                   ** IGNORE IT
  307.                 svgfx_PixelBits    = 8;                   ** or == 24
  308.                 svgfx_ColorDepth   = [used PixelBits]
  309.  
  310.    
  311.    svgfx_ColorDepth always describes the _real_ ColorDepth of the graphics,
  312.    which means the stored number of planes for BITPLANE data and the number
  313.    of _actually_ used pixelbits for ONEPLANE data.
  314.  
  315.    If svgfx_PixelBits is 24, svgfx_ColorDepth will perhaps always be 24, too.
  316.    But if svgfx_PixelBits is 8, it may be anything between 1 and 8.
  317.  
  318.    The reason is, that e.g. GIF pictures are always stored 8 Bit-wide,
  319.    no matter if they contain 4, 8 or 256 Colors.
  320.    This is just because these 8 Bit are simply a ColorRegister index
  321.    (into the field of RGB-Colors : svgfx_Colors).
  322.  
  323.    OK, there's no problem in displaying a ONEPLANE-8 graphics on a 256 Color
  324.    Screen, no matter which value svgfx_ColorDepth actually contains.
  325.    But if svgfx_ColorDepth is, let's say, only 4, this will be just a
  326.    waste of memory (and the last 256-16 = 240 colors will be black, anyway).
  327.  
  328.    So finally we can say, that the data in a ONEPLANE SV_GfxBuffer is just
  329.    stored the same way, as e.g. in ChunkyPixel modes of VGA-like Graphic Cards
  330.    or in the source-buffers for GfxLibs's WritePixelLine8().
  331.    (See "graphics.library"'s AutoDocs for more information on ChunkyPixel
  332.     buffer (PixelLine8) handling under V37/39 with ECS/AGA.)
  333.  
  334.  
  335.    Which kind of data-storage is more likely ?
  336.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~   
  337.    The ways of data-storage only depends the specific SVObjects.
  338.  
  339.    Some Examples :
  340.  
  341.    FileType   BufferType     PixelBits    ColorDepth
  342.  
  343.    GIF        ONEPLANE       8            1..8
  344.    ILBM       BITPLANE       -            1..8
  345.    JPGE       ONEPLANE       8/24         8/24
  346.  
  347.  
  348.    So any program, which supports GfxBuffers should handle both formats.
  349.    This is not difficult, since superviewsupport.library
  350.    contains functions to convert ONEPLANE buffers into BITPLANE buffers
  351.    and vice versa.
  352.    So you actually only have to support one of the data-storage alternatives.
  353.  
  354.    (See Example-SourceCodes for more and detailed information !)
  355. */
  356.  
  357. #endif /* SUPERVIEW_SUPERVIEW_H */
  358.