1 /* Copyright (C) 1998, 1999 Aladdin Enterprises. All rights reserved. 2 3 This software is provided AS-IS with no warranty, either express or 4 implied. 5 6 This software is distributed under license and may not be copied, 7 modified or distributed except as expressly authorized under the terms 8 of the license contained in the file LICENSE in this distribution. 9 10 For more information about licensing, please refer to 11 http://www.ghostscript.com/licensing/. For information on 12 commercial licensing, go to http://www.artifex.com/licensing/ or 13 contact Artifex Software, Inc., 101 Lucas Valley Road #110, 14 San Rafael, CA 94903, U.S.A., +1(415)492-9861. 15 */ 16 17 /* $Id: gsbitmap.h,v 1.4 2002/02/21 22:24:52 giles Exp $ */ 18 /* Library "client" bitmap structures */ 19 20 #ifndef gsbitmap_INCLUDED 21 #define gsbitmap_INCLUDED 22 23 #include "gsstype.h" /* for extern_st */ 24 25 /* 26 * The Ghostscript library stores all bitmaps bit-big-endian (i.e., the 0x80 27 * bit of the first byte corresponds to x=0), as a sequence of bytes (i.e., 28 * you can't do word-oriented operations on them if you're on a 29 * little-endian platform like the Intel 80x86 or VAX). The first scan line 30 * corresponds to y=0 in whatever coordinate system is relevant. 31 * 32 * The structures defined here are for APIs that don't impose any alignment 33 * restrictions on either the starting address or the raster (distance 34 * between scan lines) of bitmap data. The structures defined in gxbitmap.h 35 * do impose alignment restrictions, so that the library can use more 36 * efficient algorithms; they are declared with identical contents to the 37 * ones defined here, so that one can cast between them under appropriate 38 * circumstances (aligned to unaligned is always safe; unaligned to 39 * aligned is safe if one knows somehow that the data are actually aligned.) 40 * 41 * In this file we also provide structures that include depth information. 42 * It probably was a design mistake not to include this information in the 43 * gx structures as well. 44 */ 45 46 /* 47 * Drivers such as the X driver and the command list (band list) driver 48 * benefit greatly by being able to cache bitmaps (tiles and characters) 49 * and refer to them later. To help them recognize when a bitmap is the 50 * same as one that they have seen before, the core code passes an optional 51 * ID with the property that if two bitmaps have the same ID, they are 52 * guaranteed to have the same contents. (The converse is *not* true, 53 * however: two bitmaps may have different IDs and still be the same.) 54 */ 55 typedef gs_id gs_bitmap_id; 56 57 /* Define a special value to indicate "no identifier". */ 58 #define gs_no_bitmap_id gs_no_id 59 60 /* 61 * In its simplest form, the client bitmap structure does not specify a 62 * depth, expecting it to be implicit in the context of use. In many cases 63 * it is possible to guess this by comparing size.x and raster, but of 64 * course code should not rely on this. See also gs_depth_bitmap below. 65 * Requirements: 66 * size.x > 0, size.y > 0 67 * If size.y > 1, 68 * raster >= (size.x * depth + 7) / 8 69 */ 70 #define gs_bitmap_common(data_type) \ 71 data_type * data; /* pointer to the data */ \ 72 int raster; /* increment between scanlines, bytes */ \ 73 gs_int_point size; /* width and height */ \ 74 gs_bitmap_id id /* usually unused */ 75 76 typedef struct gs_bitmap_s { 77 gs_bitmap_common(byte); 78 } gs_bitmap; 79 typedef struct gs_const_bitmap_s { 80 gs_bitmap_common(const byte); 81 } gs_const_bitmap; 82 83 /* 84 * For bitmaps used as halftone tiles, we may replicate the tile in 85 * X and/or Y, but it is still valuable to know the true tile dimensions 86 * (i.e., the dimensions prior to replication). Requirements: 87 * size.x % rep_width = 0 88 * size.y % rep_height = 0 89 * Unaligned bitmaps are not very likely to be used as tiles (replicated), 90 * since most of the library procedures that replicate tiles expect them 91 * to be aligned. 92 */ 93 #define gs_tile_bitmap_common(data_type) \ 94 gs_bitmap_common(data_type); \ 95 ushort rep_width, rep_height /* true size of tile */ 96 97 typedef struct gs_tile_bitmap_s { 98 gs_tile_bitmap_common(byte); 99 } gs_tile_bitmap; 100 typedef struct gs_const_tile_bitmap_s { 101 gs_tile_bitmap_common(const byte); 102 } gs_const_tile_bitmap; 103 104 /* 105 * There is no "strip" version for client bitmaps, as the strip structure is 106 * primarily used to efficiently store bitmaps rendered at an angle, and 107 * there is little reason to do so with client bitmaps. 108 * 109 * For client bitmaps it is not always apparent from context what the intended 110 * depth per sample value is. To provide for this, an extended version of the 111 * bitmap structure is provided, that handles both variable depth and 112 * interleaved color components. This structure is provided in both the 113 * normal and tiled version. 114 * 115 * Extending this line of thinking, one could also add color space information 116 * to a client bitmap structure. We have chosen not to do so, because color 117 * space is almost always derived from context, and to provide such a feature 118 * would involve additional memory-management complexity. 119 */ 120 #define gs_depth_bitmap_common(data_type) \ 121 gs_bitmap_common(data_type); \ 122 byte pix_depth; /* bits per sample */ \ 123 byte num_comps /* number of interleaved components */ \ 124 125 typedef struct gs_depth_bitmap_s { 126 gs_depth_bitmap_common(byte); 127 } gs_depth_bitmap; 128 typedef struct gs_const_depth_bitmap_s { 129 gs_depth_bitmap_common(const byte); 130 } gs_const_depth_bitmap; 131 132 #define gs_tile_depth_bitmap_common(data_type) \ 133 gs_tile_bitmap_common(data_type); \ 134 byte pix_depth; /* bits per sample */ \ 135 byte num_comps /* number of interleaved components */ \ 136 137 typedef struct gs_tile_depth_bitmap_s { 138 gs_tile_depth_bitmap_common(byte); 139 } gs_tile_depth_bitmap; 140 typedef struct gs_const_tile_depth_bitmap_s { 141 gs_tile_depth_bitmap_common(const byte); 142 } gs_const_tile_depth_bitmap; 143 144 /* 145 * For reasons that are no entirely clear, no memory management routines were 146 * provided for the aligned bitmap structures provided in gxbitmap.h. Since 147 * client bitmaps will, by nature, be created by different clients, so public 148 * memory management procedures are provided. Note that the memory management 149 * structure names retain the "gs_" prefix, to distinguish these structures 150 * from those that may be provided for the gx_*_bitmap structures. 151 * 152 * For historical reasons of no particular validity (this was where the client 153 * bitmap structure was first provided), the memory managment procedures for 154 * client bitmap structures are included in gspcolor.c. 155 */ 156 extern_st(st_gs_bitmap); 157 extern_st(st_gs_tile_bitmap); 158 extern_st(st_gs_depth_bitmap); 159 extern_st(st_gs_tile_depth_bitmap); 160 161 #define public_st_gs_bitmap() /* in gspcolor.c */ \ 162 gs_public_st_ptrs1( st_gs_bitmap, \ 163 gs_bitmap, \ 164 "client bitmap", \ 165 bitmap_enum_ptrs, \ 166 bitmap_reloc_ptrs, \ 167 data \ 168 ) 169 170 #define public_st_gs_tile_bitmap() /* in gspcolor.c */ \ 171 gs_public_st_suffix_add0_local( st_gs_tile_bitmap, \ 172 gs_tile_bitmap, \ 173 "client tile bitmap", \ 174 bitmap_enum_ptrs, \ 175 bitmap_reloc_ptrs, \ 176 st_gs_bitmap \ 177 ) 178 179 #define public_st_gs_depth_bitmap() /* in gspcolor.c */ \ 180 gs_public_st_suffix_add0_local( st_gs_depth_bitmap, \ 181 gs_depth_bitmap, \ 182 "client depth bitmap", \ 183 bitmap_enum_ptrs, \ 184 bitmap_reloc_ptrs, \ 185 st_gs_bitmap \ 186 ) 187 188 #define public_st_gs_tile_depth_bitmap()/* in gspcolor.c */ \ 189 gs_public_st_suffix_add0_local( st_gs_tile_depth_bitmap, \ 190 gs_tile_depth_bitmap, \ 191 "client tile_depth bitmap", \ 192 bitmap_enum_ptrs, \ 193 bitmap_reloc_ptrs, \ 194 st_gs_tile_bitmap \ 195 ) 196 197 #endif /* gsbitmap_INCLUDED */ 198