components/x11/rasterfile/src/rasterfile.5

   1 .\" Copyright (c) 1994, Oracle and/or its affiliates. All rights reserved.
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining a
   4 .\" copy of this software and associated documentation files (the "Software"),
   5 .\" to deal in the Software without restriction, including without limitation
   6 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   7 .\" and/or sell copies of the Software, and to permit persons to whom the
   8 .\" Software is furnished to do so, subject to the following conditions:
   9 .\"
  10 .\" The above copyright notice and this permission notice (including the next
  11 .\" paragraph) shall be included in all copies or substantial portions of the
  12 .\" Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  17 .\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18 .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  19 .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  20 .\" DEALINGS IN THE SOFTWARE.
  21 .TH rasterfile 5 "29 March 1994"
  22 .IX "images" "ras" "images" "rasterfile image format \(em \f3rasterfile\f1(5)"
  23 .IX "rasterfile" "" "\f3rasterfile\f1(5) \(em raster image format file " ""
  24 .SH NAME
  25 rasterfile \- Sun's file format for raster images
  26 .SH SYNOPSIS
  27 .B #include <pixrect/rasterfile.h>
  28 .SH DESCRIPTION
  29 .LP
  30 A rasterfile is composed of three parts:
  31 first, a header containing 8 integers;
  32 second, a (possibly empty) set of colormap values;
  33 and third, the pixel image, stored a line at
  34 a time, in increasing
  35 .I y
  36 order.  The image is layed out in the file
  37 as in a memory pixrect.  Each line of the
  38 image is rounded up to the nearest 16 bits.
  39 .IX "rasterfile"
  40 .LP
  41 The header is defined by the following structure:
  42 .LP
  43 .RS
  44 .nf
  45 struct rasterfile {
  46         int     ras_magic;
  47         int     ras_width;
  48         int     ras_height;
  49         int     ras_depth;
  50         int     ras_length;
  51         int     ras_type;
  52         int     ras_maptype;
  53         int     ras_maplength;
  54 };
  55 .fi
  56 .ft R
  57 .RE
  58 .LP
  59 The
  60 .I ras_magic
  61 field always contains the following constant:
  62 .IP
  63 .B #define      \s-1RAS_MAGIC\s0        0x59a66a95
  64 .LP
  65 The
  66 .IR ras_width ,
  67 .IR ras_height ,
  68 and
  69 .I ras_depth
  70 fields contain the image's width and height in pixels,
  71 and its depth in bits per pixel, respectively.
  72 The depth is either 1 or 8, corresponding
  73 to standard frame buffer depths.  The
  74 .I ras_length
  75 field contains the length in bytes of the image data.
  76 For an unencoded image, this number is
  77 computable from the
  78 .IR ras_width ,
  79 .IR ras_height ,
  80 and
  81 .I ras_depth
  82 fields, but for an encoded image it must be explicitly stored in
  83 order to be available without decoding the image itself.
  84 Note: the length of the header and of
  85 the (possibly empty)
  86 colormap values are not included in the value of the
  87 .I ras_length
  88 field; it is only the image data length.
  89 For historical reasons, files of type
  90 .SM RT_OLD
  91 will usually have a 0 in the
  92 .I ras_length
  93 field, and software expecting to encounter such files
  94 should be prepared to compute the actual
  95 image data length if needed.  The
  96 .I ras_maptype
  97 and
  98 .I ras_maplength
  99 fields contain the type and length in
 100 bytes of the colormap values, respectively.  If
 101 .I ras_maptype
 102 is not
 103 .SM RMT_NONE
 104 and the
 105 .I ras_maplength
 106 is not 0, then the colormap values are the
 107 .I ras_maplength
 108 bytes immediately after the header.
 109 These values are either uninterpreted
 110 bytes (usually with the
 111 .I ras_maptype
 112 set to
 113 .SM RMT_RAW\s0)
 114 or the equal length red, green and blue
 115 vectors, in that order (when the
 116 .I ras_maptype
 117 is
 118 .SM RMT_EQUAL_RGB\s0).
 119 In the latter case, the
 120 .I ras_maplength
 121 must be three times the size in bytes
 122 of any one of the vectors.