1 /* $Id: fb.h,v 1.4 2008/09/24 22:45:55 fredette Exp $ */
2 
3 /* tme/generic/fb.h - header file for generic framebuffer support: */
4 
5 /*
6  * Copyright (c) 2003 Matt Fredette
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  * 1. Redistributions of source code must retain the above copyright
13  *    notice, this list of conditions and the following disclaimer.
14  * 2. Redistributions in binary form must reproduce the above copyright
15  *    notice, this list of conditions and the following disclaimer in the
16  *    documentation and/or other materials provided with the distribution.
17  * 3. All advertising materials mentioning features or use of this software
18  *    must display the following acknowledgement:
19  *      This product includes software developed by Matt Fredette.
20  * 4. The name of the author may not be used to endorse or promote products
21  *    derived from this software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
24  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
25  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
26  * DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
27  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
28  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
29  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
31  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
32  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33  * POSSIBILITY OF SUCH DAMAGE.
34  */
35 
36 #ifndef _TME_GENERIC_FB_H
37 #define _TME_GENERIC_FB_H
38 
39 #include <tme/common.h>
40 _TME_RCSID("$Id: fb.h,v 1.4 2008/09/24 22:45:55 fredette Exp $");
41 
42 /* includes: */
43 #include <tme/element.h>
44 
45 /* macros: */
46 
47 /* translation scaling: */
48 #define TME_FB_XLAT_SCALE_HALF		(2 / 2)
49 #define TME_FB_XLAT_SCALE_NONE		(2)
50 #define TME_FB_XLAT_SCALE_DOUBLE	(2 * 2)
51 
52 /* the different framebuffer classes: */
53 #define TME_FB_XLAT_CLASS_ANY		(0)
54 #define TME_FB_XLAT_CLASS_MONOCHROME	(1)
55 #define TME_FB_XLAT_CLASS_COLOR		(2)
56 
57 /* the different mapping types: */
58 #define TME_FB_XLAT_MAP_ANY		(0)
59 #define TME_FB_XLAT_MAP_LINEAR		(1)
60 #define TME_FB_XLAT_MAP_INDEX		(2)
61 
62 /* when we have primary intensities but no destination pixel subfield
63    masks, we use these masks: */
64 #define TME_FB_XLAT_MASK_DEFAULT_G	(0x07e0)
65 #define TME_FB_XLAT_MASK_DEFAULT_R	(0xf800)
66 #define TME_FB_XLAT_MASK_DEFAULT_B	(0x001f)
67 
68 /* since you can't have a noncontiguous subfield mask, we use one as
69    the wildcarded subfield mask: */
70 #define TME_FB_XLAT_MASK_ANY		(0x5)
71 
72 /* this is the maximum value that will be used as an index in an index
73    mapping: */
74 #define TME_FB_XLAT_MAP_INDEX_MASK_MAX	(0xffff)
75 #if (TME_FB_XLAT_MAP_INDEX_MASK_MAX > 0xffff)
76 #error "maximum index mask is greater than 0xffff"
77 #endif
78 #if ((TME_FB_XLAT_MASK_DEFAULT_G | TME_FB_XLAT_MASK_DEFAULT_R | TME_FB_XLAT_MASK_DEFAULT_B) > TME_FB_XLAT_MAP_INDEX_MASK_MAX)
79 #error "default masks are bigger than the maximum index mask"
80 #endif
81 
82 /* TME_FB_XLAT_MAP_BASE_MASK returns a base mask, one without any
83    least significant zero bits: */
84 #define TME_FB_XLAT_MAP_BASE_MASK(mask)			\
85   ((mask) / _TME_FIELD_MASK_FACTOR(mask))
86 
87 /* the return value of tme_fb_xlat_colors_get() is a colorset
88    signature.  if TME_FB_COLORSET_NONE, the colorset is tied, at least
89    in part, to the source framebuffer characteristics.  otherwise, the
90    colorset is only tied to the destination framebuffer
91    characteristics - and two such colorsets, with the same signature
92    and with the same destination framebuffer characteristics, will
93    always be identical.  this allows the caller to avoid unnecessary
94    color reallocation: */
95 #define TME_FB_COLORSET_NONE		(0)
96 
97 /* types: */
98 
99 /* a framebuffer connection: */
100 struct tme_fb_connection {
101 
102   /* the generic connection side: */
103   struct tme_connection tme_fb_connection;
104 
105   /* this is called when the framebuffer mode changes: */
106   int (*tme_fb_connection_mode_change) _TME_P((struct tme_fb_connection *));
107 
108   /* this is called before the framebuffer's display is updated: */
109   int (*tme_fb_connection_update) _TME_P((struct tme_fb_connection *));
110 
111   /* scanlines have this many displayed pixels: */
112   unsigned int tme_fb_connection_width;
113 
114   /* frames have this many displayed scanlines: */
115   unsigned int tme_fb_connection_height;
116 
117   /* pixels have this depth, in bits: */
118   unsigned int tme_fb_connection_depth;
119 
120   /* pixels have this many bits.  this must be at least the same as
121      the depth, but it can also be greater, and it must be a power of
122      two: */
123   unsigned int tme_fb_connection_bits_per_pixel;
124 
125   /* scanlines begin with bits for this many *undisplayed* pixels.
126      these pixels are not included in tme_fb_connection_width: */
127   unsigned int tme_fb_connection_skipx;
128 
129   /* scanlines are padded to this many bits.  this must be a power of
130      two greater than or equal to 8: */
131   unsigned int tme_fb_connection_scanline_pad;
132 
133   /* scanline data has this endianness.  this is either TME_ENDIAN_BIG
134      or TME_ENDIAN_LITTLE: */
135   unsigned int tme_fb_connection_order;
136 
137   /* the real framebuffer memory: */
138   tme_uint8_t *tme_fb_connection_buffer;
139 
140   /* the offsets of the first and last bytes updated in the real
141      framebuffer memory.  if the first offset is greater than the last
142      offset, none of the framebuffer memory was updated: */
143   tme_uint32_t tme_fb_connection_offset_updated_first;
144   tme_uint32_t tme_fb_connection_offset_updated_last;
145 
146   /* the class of the framebuffer: */
147   unsigned int tme_fb_connection_class;
148 
149   /* any masks for pixel value subfields: */
150   tme_uint32_t tme_fb_connection_mask_g;
151   tme_uint32_t tme_fb_connection_mask_r;
152   tme_uint32_t tme_fb_connection_mask_b;
153 
154   /* these are used for index-mapping pixel values or pixel subfield
155      values to intensities, or vice-versa.  if these are NULL,
156      everything is linearly mapped: */
157   const void *tme_fb_connection_map_g;
158   const void *tme_fb_connection_map_r;
159   const void *tme_fb_connection_map_b;
160 
161   /* if this is nonzero, intensities are inverted (a smaller value is
162      more intense than a greater value): */
163   int tme_fb_connection_inverted;
164 
165   /* in a source framebuffer connection, this is the size of an
166      intensity, in bits.  this cannot be greater than 16: */
167   unsigned int tme_fb_connection_map_bits;
168 
169   /* in a destination framebuffer connection, this is used to map
170      source pixel values into destination pixel values: */
171   const tme_uint32_t *tme_fb_connection_map_pixel;
172   tme_uint32_t tme_fb_connection_map_pixel_count;
173 };
174 
175 /* one frame buffer translation function: */
176 struct tme_fb_xlat {
177 
178   /* the translation function itself: */
179   int (*tme_fb_xlat_func) _TME_P((struct tme_fb_connection *, struct tme_fb_connection *));
180 
181   /* iff nonzero, this function applies only when scanlines have this
182      many displayed pixels: */
183   unsigned int tme_fb_xlat_width;
184 
185   /* iff nonzero, this function applies only when there are this many
186      scanlines: */
187   unsigned int tme_fb_xlat_height;
188 
189   /* the scaling that this function does: */
190   unsigned int tme_fb_xlat_scale;
191 
192   /* iff nonzero, this function applies only when source pixels have
193      this depth: */
194   unsigned int tme_fb_xlat_src_depth;
195 
196   /* iff nonzero, this function applies only when source pixels have
197      this many bits: */
198   unsigned int tme_fb_xlat_src_bits_per_pixel;
199 
200   /* iff >= 0, this function applies only when source scanlines begin
201      with this many *undisplayed* pixels.  these pixels are not
202      counted in tme_fb_xlat_width: */
203   int tme_fb_xlat_src_skipx;
204 
205   /* iff nonzero, this function applies only when source scanlines are
206      padded to this many bits: */
207   unsigned int tme_fb_xlat_src_scanline_pad;
208 
209   /* this function applies only when source scanline data has this
210      order (endianness): */
211   int tme_fb_xlat_src_order;
212 
213   /* iff not TME_FB_XLAT_CLASS_ANY, this function applies only to
214      a source framebuffer of this class: */
215   int tme_fb_xlat_src_class;
216 
217   /* iff not TME_FB_XLAT_MAP_ANY, this function applies only to
218      a source framebuffer with this type of intensity mapping: */
219   int tme_fb_xlat_src_map;
220 
221   /* iff nonzero, this function applies only when source intensities
222      have this many bits: */
223   unsigned int tme_fb_xlat_src_map_bits;
224 
225   /* iff not TME_FB_XLAT_MASK_ANY, this function applies only to a
226      source framebuffer with these subfield masks: */
227   tme_uint32_t tme_fb_xlat_src_mask_g;
228   tme_uint32_t tme_fb_xlat_src_mask_r;
229   tme_uint32_t tme_fb_xlat_src_mask_b;
230 
231   /* iff nonzero, this function applies only when destination pixels
232      have this depth: */
233   unsigned int tme_fb_xlat_dst_depth;
234 
235   /* iff nonzero, this function applies only when destination pixels
236      have this many bits: */
237   unsigned int tme_fb_xlat_dst_bits_per_pixel;
238 
239   /* iff >= 0, this function applies only when destination scanlines
240      begin with this many *undisplayed* pixels.  these pixels are not
241      counted in tme_fb_xlat_width: */
242   int tme_fb_xlat_dst_skipx;
243 
244   /* iff nonzero, this function applies only when destination
245      scanlines are padded to this many bits: */
246   unsigned int tme_fb_xlat_dst_scanline_pad;
247 
248   /* this function applies only when destination scanline data has
249      this order (endianness): */
250   int tme_fb_xlat_dst_order;
251 
252   /* iff not TME_FB_XLAT_MAP_ANY, this function applies only to
253      a destination framebuffer with this type of intensity mapping: */
254   int tme_fb_xlat_dst_map;
255 
256   /* iff not TME_FB_XLAT_MASK_ANY, this function applies only to a
257      destination framebuffer with these subfield masks: */
258   tme_uint32_t tme_fb_xlat_dst_mask_g;
259   tme_uint32_t tme_fb_xlat_dst_mask_r;
260   tme_uint32_t tme_fb_xlat_dst_mask_b;
261 };
262 
263 /* a color: */
264 struct tme_fb_color {
265   tme_uint32_t tme_fb_color_pixel;
266   tme_uint16_t tme_fb_color_value_g;
267   tme_uint16_t tme_fb_color_value_r;
268   tme_uint16_t tme_fb_color_value_b;
269 };
270 
271 /* prototypes: */
272 _tme_const struct tme_fb_xlat *tme_fb_xlat_best _TME_P((_tme_const struct tme_fb_xlat *));
273 int tme_fb_xlat_is_optimal _TME_P((_tme_const struct tme_fb_xlat *));
274 int tme_fb_xlat_alloc_src _TME_P((struct tme_fb_connection *));
275 void tme_fb_xlat_redraw _TME_P((struct tme_fb_connection *));
276 tme_uint32_t tme_fb_xlat_colors_get _TME_P((const struct tme_fb_connection *,
277 					    unsigned int,
278 					    struct tme_fb_connection *,
279 					    struct tme_fb_color **));
280 void tme_fb_xlat_colors_set _TME_P((const struct tme_fb_connection *,
281 				    unsigned int,
282 				    struct tme_fb_connection *,
283 				    struct tme_fb_color *));
284 int tme_fb_connection_score _TME_P((struct tme_connection *, unsigned int *));
285 
286 #endif /* !_TME_GENERIC_FB_H */
287