1 /* 2 * Cogl 3 * 4 * A Low Level GPU Graphics and Utilities API 5 * 6 * Copyright (C) 2008,2009 Intel Corporation. 7 * 8 * Permission is hereby granted, free of charge, to any person 9 * obtaining a copy of this software and associated documentation 10 * files (the "Software"), to deal in the Software without 11 * restriction, including without limitation the rights to use, copy, 12 * modify, merge, publish, distribute, sublicense, and/or sell copies 13 * of the Software, and to permit persons to whom the Software is 14 * furnished to do so, subject to the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be 17 * included in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 23 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 24 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 25 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 26 * SOFTWARE. 27 * 28 * 29 */ 30 31 #if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION) 32 #error "Only <cogl/cogl.h> can be included directly." 33 #endif 34 35 #ifndef __COGL_PIXEL_FORMAT_H__ 36 #define __COGL_PIXEL_FORMAT_H__ 37 38 #include <stdint.h> 39 #include <stddef.h> 40 41 #include <cogl/cogl-defines.h> 42 #include <cogl/cogl-macros.h> 43 44 #include <glib.h> 45 #include <glib-object.h> 46 47 G_BEGIN_DECLS 48 49 /** 50 * SECTION:cogl-pixel-format 51 * @short_description: Pixel formats supported by Cogl 52 * 53 * The pixel format of an image descrbes how the bits of each pixel are 54 * represented in memory. For example: an image can be laid out as one long 55 * sequence of pixels, where each pixel is a sequence of 8 bits of Red, Green 56 * and Blue. The amount of bits that are used can be different for each pixel 57 * format, as well as the components (for example an Alpha layer to include 58 * transparency, or non_RGBA). 59 * 60 * Other examples of factors that can influence the layout in memory are the 61 * system's endianness. 62 */ 63 64 #define COGL_A_BIT (1 << 4) 65 #define COGL_BGR_BIT (1 << 5) 66 #define COGL_AFIRST_BIT (1 << 6) 67 #define COGL_PREMULT_BIT (1 << 7) 68 #define COGL_DEPTH_BIT (1 << 8) 69 #define COGL_STENCIL_BIT (1 << 9) 70 71 /* XXX: Notes to those adding new formats here... 72 * 73 * First this diagram outlines how we allocate the 32bits of a 74 * CoglPixelFormat currently... 75 * 76 * 6 bits for flags 77 * |-----| 78 * enum unused 4 bits for the bytes-per-pixel 79 * and component alignment info 80 * |------| |-------------| |--| 81 * 00000000 xxxxxxxx xxxxxxSD PFBA0000 82 * ^ stencil 83 * ^ depth 84 * ^ premult 85 * ^ alpha first 86 * ^ bgr order 87 * ^ has alpha 88 * 89 * The most awkward part about the formats is how we use the last 4 90 * bits to encode the bytes per pixel and component alignment 91 * information. Ideally we should have had 3 bits for the bpp and a 92 * flag for alignment but we didn't plan for that in advance so we 93 * instead use a small lookup table to query the bpp and whether the 94 * components are byte aligned or not. 95 * 96 * The mapping is the following (see discussion on bug #660188): 97 * 98 * 0 = undefined 99 * 1, 8 = 1 bpp (e.g. A_8, G_8) 100 * 2 = 3 bpp, aligned (e.g. 888) 101 * 3 = 4 bpp, aligned (e.g. 8888) 102 * 4-6 = 2 bpp, not aligned (e.g. 565, 4444, 5551) 103 * 7 = YUV: undefined bpp, undefined alignment 104 * 9 = 2 bpp, aligned 105 * 10 = depth, aligned (8, 16, 24, 32, 32f) 106 * 11 = 8 bpp fp16 107 * 12 = 3 bpp, not aligned 108 * 13 = 4 bpp, not aligned (e.g. 2101010) 109 * 14-15 = undefined 110 * 111 * Note: the gap at 10-11 is just because we wanted to maintain that 112 * all non-aligned formats have the third bit set in case that's 113 * useful later. 114 * 115 * Since we don't want to waste bits adding more and more flags, we'd 116 * like to see most new pixel formats that can't be represented 117 * uniquely with the existing flags in the least significant byte 118 * simply be enumerated with sequential values in the most significant 119 * enum byte. 120 * 121 * Note: Cogl avoids exposing any padded XRGB or RGBX formats and 122 * instead we leave it up to applications to decided whether they 123 * consider the A component as padding or valid data. We shouldn't 124 * change this policy without good reasoning. 125 * 126 * So to add a new format: 127 * 1) Use the mapping table above to figure out what to but in 128 * the lowest nibble. 129 * 2) OR in the COGL_PREMULT_BIT, COGL_AFIRST_BIT, COGL_A_BIT and 130 * COGL_BGR_BIT flags as appropriate. 131 * 3) If the result is not yet unique then also combine with an 132 * increment of the last sequence number in the most significant 133 * byte. 134 * 135 * The last sequence number used was 0 (i.e. no formats currently need 136 * a sequence number) 137 * Update this note whenever a new sequence number is used. 138 */ 139 /** 140 * CoglPixelFormat: 141 * @COGL_PIXEL_FORMAT_ANY: Any format 142 * @COGL_PIXEL_FORMAT_A_8: 8 bits alpha mask 143 * @COGL_PIXEL_FORMAT_RG_88: RG, 16 bits. Note that red-green textures 144 * are only available if %COGL_FEATURE_ID_TEXTURE_RG is advertised. 145 * See cogl_texture_set_components() for details. 146 * @COGL_PIXEL_FORMAT_RGB_565: RGB, 16 bits 147 * @COGL_PIXEL_FORMAT_RGBA_4444: RGBA, 16 bits 148 * @COGL_PIXEL_FORMAT_RGBA_5551: RGBA, 16 bits 149 * @COGL_PIXEL_FORMAT_YUV: Not currently supported 150 * @COGL_PIXEL_FORMAT_G_8: Single luminance component 151 * @COGL_PIXEL_FORMAT_RGB_888: RGB, 24 bits 152 * @COGL_PIXEL_FORMAT_BGR_888: BGR, 24 bits 153 * @COGL_PIXEL_FORMAT_RGBA_8888: RGBA, 32 bits 154 * @COGL_PIXEL_FORMAT_BGRA_8888: BGRA, 32 bits 155 * @COGL_PIXEL_FORMAT_ARGB_8888: ARGB, 32 bits 156 * @COGL_PIXEL_FORMAT_ABGR_8888: ABGR, 32 bits 157 * @COGL_PIXEL_FORMAT_RGBA_1010102 : RGBA, 32 bits, 10 bpc 158 * @COGL_PIXEL_FORMAT_BGRA_1010102 : BGRA, 32 bits, 10 bpc 159 * @COGL_PIXEL_FORMAT_ARGB_2101010 : ARGB, 32 bits, 10 bpc 160 * @COGL_PIXEL_FORMAT_ABGR_2101010 : ABGR, 32 bits, 10 bpc 161 * @COGL_PIXEL_FORMAT_RGBA_8888_PRE: Premultiplied RGBA, 32 bits 162 * @COGL_PIXEL_FORMAT_BGRA_8888_PRE: Premultiplied BGRA, 32 bits 163 * @COGL_PIXEL_FORMAT_ARGB_8888_PRE: Premultiplied ARGB, 32 bits 164 * @COGL_PIXEL_FORMAT_ABGR_8888_PRE: Premultiplied ABGR, 32 bits 165 * @COGL_PIXEL_FORMAT_RGBA_4444_PRE: Premultiplied RGBA, 16 bits 166 * @COGL_PIXEL_FORMAT_RGBA_5551_PRE: Premultiplied RGBA, 16 bits 167 * @COGL_PIXEL_FORMAT_RGBA_1010102_PRE: Premultiplied RGBA, 32 bits, 10 bpc 168 * @COGL_PIXEL_FORMAT_BGRA_1010102_PRE: Premultiplied BGRA, 32 bits, 10 bpc 169 * @COGL_PIXEL_FORMAT_ARGB_2101010_PRE: Premultiplied ARGB, 32 bits, 10 bpc 170 * @COGL_PIXEL_FORMAT_ABGR_2101010_PRE: Premultiplied ABGR, 32 bits, 10 bpc 171 * @COGL_PIXEL_FORMAT_RGBA_FP_16161616: RGBA half floating point, 64 bit 172 * @COGL_PIXEL_FORMAT_BGRA_FP_16161616: BGRA half floating point, 64 bit 173 * @COGL_PIXEL_FORMAT_ARGB_FP_16161616: ARGB half floating point, 64 bit 174 * @COGL_PIXEL_FORMAT_ABGR_FP_16161616: ABGR half floating point, 64 bit 175 * @COGL_PIXEL_FORMAT_RGBA_FP_16161616_PRE: Premultiplied RGBA half floating point, 64 bit 176 * @COGL_PIXEL_FORMAT_BGRA_FP_16161616_PRE: Premultiplied BGRA half floating point, 64 bit 177 * @COGL_PIXEL_FORMAT_ARGB_FP_16161616_PRE: Premultiplied ARGB half floating point, 64 bit 178 * @COGL_PIXEL_FORMAT_ABGR_FP_16161616_PRE: Premultiplied ABGR half floating point, 64 bit 179 * 180 * Pixel formats used by Cogl. For the formats with a byte per 181 * component, the order of the components specify the order in 182 * increasing memory addresses. So for example 183 * %COGL_PIXEL_FORMAT_RGB_888 would have the red component in the 184 * lowest address, green in the next address and blue after that 185 * regardless of the endianness of the system. 186 * 187 * For the formats with non byte aligned components the component 188 * order specifies the order within a 16-bit or 32-bit number from 189 * most significant bit to least significant. So for 190 * %COGL_PIXEL_FORMAT_RGB_565, the red component would be in bits 191 * 11-15, the green component would be in 6-11 and the blue component 192 * would be in 1-5. Therefore the order in memory depends on the 193 * endianness of the system. 194 * 195 * When uploading a texture %COGL_PIXEL_FORMAT_ANY can be used as the 196 * internal format. Cogl will try to pick the best format to use 197 * internally and convert the texture data if necessary. 198 * 199 * Since: 0.8 200 */ 201 typedef enum /*< prefix=COGL_PIXEL_FORMAT >*/ 202 { 203 COGL_PIXEL_FORMAT_ANY = 0, 204 COGL_PIXEL_FORMAT_A_8 = 1 | COGL_A_BIT, 205 206 COGL_PIXEL_FORMAT_RGB_565 = 4, 207 COGL_PIXEL_FORMAT_RGBA_4444 = 5 | COGL_A_BIT, 208 COGL_PIXEL_FORMAT_RGBA_5551 = 6 | COGL_A_BIT, 209 COGL_PIXEL_FORMAT_YUV = 7, 210 COGL_PIXEL_FORMAT_G_8 = 8, 211 212 COGL_PIXEL_FORMAT_RG_88 = 9, 213 214 COGL_PIXEL_FORMAT_RGB_888 = 2, 215 COGL_PIXEL_FORMAT_BGR_888 = (2 | COGL_BGR_BIT), 216 217 COGL_PIXEL_FORMAT_RGBA_8888 = (3 | COGL_A_BIT), 218 COGL_PIXEL_FORMAT_BGRA_8888 = (3 | COGL_A_BIT | COGL_BGR_BIT), 219 COGL_PIXEL_FORMAT_ARGB_8888 = (3 | COGL_A_BIT | COGL_AFIRST_BIT), 220 COGL_PIXEL_FORMAT_ABGR_8888 = (3 | COGL_A_BIT | COGL_BGR_BIT | COGL_AFIRST_BIT), 221 222 COGL_PIXEL_FORMAT_RGBA_1010102 = (13 | COGL_A_BIT), 223 COGL_PIXEL_FORMAT_BGRA_1010102 = (13 | COGL_A_BIT | COGL_BGR_BIT), 224 COGL_PIXEL_FORMAT_XRGB_2101010 = (13 | COGL_AFIRST_BIT), 225 COGL_PIXEL_FORMAT_ARGB_2101010 = (13 | COGL_A_BIT | COGL_AFIRST_BIT), 226 COGL_PIXEL_FORMAT_XBGR_2101010 = (13 | COGL_BGR_BIT | COGL_AFIRST_BIT), 227 COGL_PIXEL_FORMAT_ABGR_2101010 = (13 | COGL_A_BIT | COGL_BGR_BIT | COGL_AFIRST_BIT), 228 229 COGL_PIXEL_FORMAT_RGBA_FP_16161616 = (11 | COGL_A_BIT), 230 COGL_PIXEL_FORMAT_BGRA_FP_16161616 = (11 | COGL_A_BIT | COGL_BGR_BIT), 231 COGL_PIXEL_FORMAT_XRGB_FP_16161616 = (11 | COGL_AFIRST_BIT), 232 COGL_PIXEL_FORMAT_ARGB_FP_16161616 = (11 | COGL_A_BIT | COGL_AFIRST_BIT), 233 COGL_PIXEL_FORMAT_XBGR_FP_16161616 = (11 | COGL_BGR_BIT | COGL_AFIRST_BIT), 234 COGL_PIXEL_FORMAT_ABGR_FP_16161616 = (11 | COGL_A_BIT | COGL_BGR_BIT | COGL_AFIRST_BIT), 235 236 COGL_PIXEL_FORMAT_RGBA_8888_PRE = (3 | COGL_A_BIT | COGL_PREMULT_BIT), 237 COGL_PIXEL_FORMAT_BGRA_8888_PRE = (3 | COGL_A_BIT | COGL_PREMULT_BIT | COGL_BGR_BIT), 238 COGL_PIXEL_FORMAT_ARGB_8888_PRE = (3 | COGL_A_BIT | COGL_PREMULT_BIT | COGL_AFIRST_BIT), 239 COGL_PIXEL_FORMAT_ABGR_8888_PRE = (3 | COGL_A_BIT | COGL_PREMULT_BIT | COGL_BGR_BIT | COGL_AFIRST_BIT), 240 COGL_PIXEL_FORMAT_RGBA_4444_PRE = (COGL_PIXEL_FORMAT_RGBA_4444 | COGL_A_BIT | COGL_PREMULT_BIT), 241 COGL_PIXEL_FORMAT_RGBA_5551_PRE = (COGL_PIXEL_FORMAT_RGBA_5551 | COGL_A_BIT | COGL_PREMULT_BIT), 242 243 COGL_PIXEL_FORMAT_RGBA_1010102_PRE = (COGL_PIXEL_FORMAT_RGBA_1010102 | COGL_PREMULT_BIT), 244 COGL_PIXEL_FORMAT_BGRA_1010102_PRE = (COGL_PIXEL_FORMAT_BGRA_1010102 | COGL_PREMULT_BIT), 245 COGL_PIXEL_FORMAT_ARGB_2101010_PRE = (COGL_PIXEL_FORMAT_ARGB_2101010 | COGL_PREMULT_BIT), 246 COGL_PIXEL_FORMAT_ABGR_2101010_PRE = (COGL_PIXEL_FORMAT_ABGR_2101010 | COGL_PREMULT_BIT), 247 248 COGL_PIXEL_FORMAT_RGBA_FP_16161616_PRE = (11 | COGL_A_BIT | COGL_PREMULT_BIT), 249 COGL_PIXEL_FORMAT_BGRA_FP_16161616_PRE = (11 | COGL_A_BIT | COGL_PREMULT_BIT | COGL_BGR_BIT), 250 COGL_PIXEL_FORMAT_ARGB_FP_16161616_PRE = (11 | COGL_A_BIT | COGL_PREMULT_BIT | COGL_AFIRST_BIT), 251 COGL_PIXEL_FORMAT_ABGR_FP_16161616_PRE = (11 | COGL_A_BIT | COGL_PREMULT_BIT | COGL_BGR_BIT | COGL_AFIRST_BIT), 252 253 COGL_PIXEL_FORMAT_DEPTH_16 = (9 | COGL_DEPTH_BIT), 254 COGL_PIXEL_FORMAT_DEPTH_32 = (3 | COGL_DEPTH_BIT), 255 256 COGL_PIXEL_FORMAT_DEPTH_24_STENCIL_8 = (3 | COGL_DEPTH_BIT | COGL_STENCIL_BIT) 257 } CoglPixelFormat; 258 259 /** 260 * COGL_PIXEL_FORMAT_MAX_PLANES: 261 * 262 * The maximum number of planes of a pixel format (see also 263 * cogl_pixel_format_get_planes()). 264 */ 265 #define COGL_PIXEL_FORMAT_MAX_PLANES (4) 266 267 /** 268 * cogl_pixel_format_get_bytes_per_pixel: 269 * @format: The pixel format 270 * @plane: The index of the plane (should not be more than the number of planes 271 * in the given format). 272 * 273 * Queries the number of bytes per pixel for a given format in the given plane. 274 * 275 * Returns: The number of bytes per pixel in the given format's given plane. 276 */ 277 COGL_EXPORT int 278 cogl_pixel_format_get_bytes_per_pixel (CoglPixelFormat format, 279 int plane); 280 281 /* 282 * _cogl_pixel_format_has_aligned_components: 283 * @format: a #CoglPixelFormat 284 * 285 * Queries whether the ordering of the components for the given 286 * @format depend on the endianness of the host CPU or if the 287 * components can be accessed using bit shifting and bitmasking by 288 * loading a whole pixel into a word. 289 * 290 * XXX: If we ever consider making something like this public we 291 * should really try to think of a better name and come up with 292 * much clearer documentation since it really depends on what 293 * point of view you consider this from whether a format like 294 * COGL_PIXEL_FORMAT_RGBA_8888 is endian dependent. E.g. If you 295 * read an RGBA_8888 pixel into a uint32 296 * it's endian dependent how you mask out the different channels. 297 * But If you already have separate color components and you want 298 * to write them to an RGBA_8888 pixel then the bytes can be 299 * written sequentially regardless of the endianness. 300 * 301 * Return value: %TRUE if you need to consider the host CPU 302 * endianness when dealing with the given @format 303 * else %FALSE. 304 */ 305 gboolean 306 _cogl_pixel_format_is_endian_dependant (CoglPixelFormat format); 307 308 /* 309 * COGL_PIXEL_FORMAT_CAN_HAVE_PREMULT(format): 310 * @format: a #CoglPixelFormat 311 * 312 * Returns TRUE if the pixel format can take a premult bit. This is 313 * currently true for all formats that have an alpha channel except 314 * COGL_PIXEL_FORMAT_A_8 (because that doesn't have any other 315 * components to multiply by the alpha). 316 */ 317 #define COGL_PIXEL_FORMAT_CAN_HAVE_PREMULT(format) \ 318 (((format) & COGL_A_BIT) && (format) != COGL_PIXEL_FORMAT_A_8) 319 320 /** 321 * cogl_pixel_format_get_n_planes: 322 * @format: The format for which to get the number of planes 323 * 324 * Returns the number of planes the given CoglPixelFormat specifies. 325 * 326 * Returns: The no. of planes of @format (at most %COGL_PIXEL_FORMAT_MAX_PLANES) 327 */ 328 COGL_EXPORT int 329 cogl_pixel_format_get_n_planes (CoglPixelFormat format); 330 331 /** 332 * cogl_pixel_format_to_string: 333 * @format: a #CoglPixelFormat 334 * 335 * Returns a string representation of @format, useful for debugging purposes. 336 * 337 * Returns: (transfer none): A string representation of @format. 338 */ 339 COGL_EXPORT const char * 340 cogl_pixel_format_to_string (CoglPixelFormat format); 341 342 G_END_DECLS 343 344 #endif /* __COGL_PIXEL_FORMAT_H__ */ 345