workbench/classes/zune/rawimage/MCC_Rawimage.doc

   1 TABLE OF CONTENTS
   2
   3 Rawimage.mcc/Rawimage.mcc
   4 Rawimage.mcc/MUIA_Rawimage_Data
   5 \fRawimage.mcc/Rawimage.mcc
   6
   7    Rawimage.mcc is a MUI custom class which offers a comfortable way to
   8    integrate large or small images (e.g. logos, symbols for buttons, etc.)
   9    into MUI UIs. Respective images can be easily embedded directly into
  10    the program code.
  11
  12    The base format (ARGB RAW) of the data structure is compatible with
  13    the MUI_AlphaData structure, so uncompressed images also can be used
  14    directly with MUI4's \033A[0xaddr] escape sequence for text output.
  15
  16    struct MUI_AlphaData
  17    {
  18        ULONG width;
  19        ULONG height;
  20        ULONG padding[2];
  21        ULONG data[0];
  22    };
  23
  24
  25    Since embedding lots of ARGB images into the code can increase executable
  26    size noticeably (up to the point when there is more image data than actual
  27    code in the binary) Rawimage.mcc offers decompression functionality, so
  28    compressed image data can be used.
  29
  30    This is not compatible with MUI_AlphaData (yet); the two reserved padding
  31    longwords are used to specify compression format and compressed data size.
  32
  33    struct MUI_RawimageData
  34    {
  35        ULONG ri_Width;
  36        ULONG ri_Height;
  37        ULONG ri_Format;
  38        ULONG ri_Size;
  39        ULONG ri_Data[0];
  40    };
  41
  42    Filling the ri_Size field is optional when ri_Format is 0.
  43
  44    To convert an image into embedded code one of the many available tools
  45    can be used (png2c, dt2raw, bin2c, dt2rawimage, etc.). For each supported
  46    format the example code (Rawimage-Demo) contains short instructions for
  47    possible ways to do the conversion.
  48
  49    e.g. to make a bz2 compressed embedded image:
  50    > dt2raw logo.png logo.raw
  51    > bzip2 -k logo.raw
  52    > bin2c logo.raw logo.c
  53
  54    The data array needs to be prefixed with the MUIA_RawimageData structure
  55    header, e.g. like this:
  56
  57    UBYTE _image1_bz2[] = {
  58        0x00, 0x00, 0x00, 0x20, /* Width of logo.png:     32         */
  59        0x00, 0x00, 0x00, 0x20, /* Height of logo.png:    32         */
  60        'B',  'Z',  '2',  '\0', /* Format:                ARGB BZ2   */
  61        0x00, 0x00, 0x07, 0x61, /* logo.png.bz2 filesize: 1889 Bytes */
  62        (actual data follows here)
  63        ...
  64
  65 \fRawimage.mcc/MUIA_Rawimage_Data
  66
  67    NAME
  68        MUIA_Rawimage_Data -- (V20) [IS.], struct MUI_RawimageData *
  69
  70    FUNCTION
  71        Initialize a new graphic for the RawimageObject. A pointer to
  72        valid MUI_AlphaData or MUI_RawimageData needs to be passed.
  73
  74        This attribute can not be queried with get(); any possible return
  75        value is undefined.
  76
  77    EXAMPLE
  78
  79        ULONG rgbpixel[] =
  80        {
  81            0x3, /* width          */
  82            0x1, /* height         */
  83            0x0, /* no compression */
  84            0x0,  /* data size      */
  85            0xFFFF0000, 0xFF00FF00, 0xFF0000FF
  86        };
  87
  88        set(rawimgobj, MUIA_Rawimage_Data, rgbpixel);
  89 \f