KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
img.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  kos/img.h
4  Copyright (C) 2002 Dan Potter
5 
6 */
7 
8 #ifndef __KOS_IMG_H
9 #define __KOS_IMG_H
10 
11 /** \file kos/img.h
12  \brief Platform-independent image type.
13 
14  This file provides a platform-independent image type that is designed to
15  hold any sort of textures or other image data. This type contains a very
16  basic description of the image data (width, height, pixel format), as well
17  as the image data itself.
18 
19  All of the image-loading libraries in kos-ports should provide a function
20  to load the image data into one of these types.
21 
22  \author Dan Potter
23 */
24 
25 #include <sys/cdefs.h>
26 __BEGIN_DECLS
27 
28 #include <arch/types.h>
29 
30 /** \brief Platform-indpendent image type.
31 
32  You can use this type for textures or whatever you feel it's appropriate
33  for. "width" and "height" are as you would expect. "format" has a lower-half
34  which is platform-independent and used to basically describe the contained
35  data; the upper-half is platform-dependent and can hold anything (so AND it
36  off if you only want the bottom part).
37 
38  Note that in some of the more obscure formats (like the paletted formats)
39  the data interpretation may be platform dependent. Thus we also provide a
40  data length field.
41 
42  \headerfile kos/img.h
43 */
44 typedef struct kos_img {
45  void *data; /**< \brief Image data in the specified format. */
46  uint32 w; /**< \brief Width of the image. */
47  uint32 h; /**< \brief Height of the image. */
48  uint32 fmt; /**< \brief Format of the image data.
49  \see kos_img_fmts
50  \see kos_img_fmt_macros */
51  uint32 byte_count; /**< \brief Length of the image data, in bytes. */
52 } kos_img_t;
53 
54 /** \defgroup kos_img_fmt_macros Macros for accessing the format of an image
55 
56  These macros provide easy access to the fmt field of a kos_img_t object.
57 
58  @{
59 */
60 /** \brief Read the platform-independent half of the format.
61 
62  This macro masks the format of a kos_img_t to give you just the lower half
63  of the value, which contains the platform-independent half of the format.
64 
65  \param x An image format (fmt field of a kos_img_t).
66  \return The platform-independent half of the format.
67 */
68 #define KOS_IMG_FMT_I(x) ((x) & 0xffff)
69 
70 /** \brief Read the platform-specific half of the format.
71 
72  This macro masks the format of a kos_img_t to give you just the upper half
73  of the value, which contains the platform-specific half of the format.
74 
75  \param x An image format (fmt field of a kos_img_t).
76  \return The platform-specific half of the format.
77 */
78 #define KOS_IMG_FMT_D(x) (((x) >> 16) & 0xffff)
79 
80 /** \brief Build a format value from a platform-independent half and a
81  platform-specific half of the value.
82 
83  This macro combines the platform-independent and platform-specific portions
84  of an image format into a value suitable for storing as the fmt field of a
85  kos_img_t object.
86 
87  \param i The platform-independent half of the format.
88  \param d The platform-specific half of the format. This should
89  not be pre-shifted.
90  \return A complete image format value, suitable for placing in
91  the fmt variable of a kos_img_t.
92 */
93 #define KOS_IMG_FMT(i, d) ( ((i) & 0xffff) | (((d) & 0xffff) << 16) )
94 
95 /** @} */
96 
97 /** \defgroup kos_img_fmts Image format types
98 
99  This is the list of platform-independent image types that can be used as the
100  lower-half of the fmt value for a kos_img_t.
101 
102  @{
103 */
104 /** \brief Undefined or uninitialized format. */
105 #define KOS_IMG_FMT_NONE 0x00
106 
107 /** \brief 24-bpp interleaved R/G/B bytes. */
108 #define KOS_IMG_FMT_RGB888 0x01
109 
110 /** \brief 32-bpp interleaved A/R/G/B bytes. */
111 #define KOS_IMG_FMT_ARGB8888 0x02
112 
113 /** \brief 16-bpp interleaved R (5 bits), G (6 bits), B (5 bits). */
114 #define KOS_IMG_FMT_RGB565 0x03
115 
116 /** \brief 16-bpp interleaved A/R/G/B (4 bits each). */
117 #define KOS_IMG_FMT_ARGB4444 0x04
118 
119 /** \brief 16-bpp interleaved A (1 bit), R (5 bits), G (5 bits), B (5 bits).
120  \note This can also be used for RGB555 (with the top bit ignored). */
121 #define KOS_IMG_FMT_ARGB1555 0x05
122 
123 /** \brief Paletted, 4 bits per pixel (16 colors). */
124 #define KOS_IMG_FMT_PAL4BPP 0x06
125 
126 /** \brief Paletted, 8 bits per pixel (256 colors). */
127 #define KOS_IMG_FMT_PAL8BPP 0x07
128 
129 /** \brief 8-bit Y (4 bits), U (2 bits), V (2 bits). */
130 #define KOS_IMG_FMT_YUV422 0x08
131 
132 /** \brief 15-bpp interleaved B (5 bits), G (6 bits), R (5 bits). */
133 #define KOS_IMG_FMT_BGR565 0x09
134 
135 /** \brief 32-bpp interleaved R/G/B/A bytes. */
136 #define KOS_IMG_FMT_RGBA8888 0x10
137 
138 /** \brief Basic format mask (not an actual format value). */
139 #define KOS_IMG_FMT_MASK 0xff
140 
141 /** \brief X axis of image data is inverted (stored right to left). */
142 #define KOS_IMG_INVERTED_X 0x0100
143 
144 /** \brief Y axis of image data is inverted (stored bottom to top). */
145 #define KOS_IMG_INVERTED_Y 0x0200
146 
147 /** \brief The image is not the owner of the image data buffer.
148 
149  This generally implies that the image data is stored in ROM and thus cannot
150  be freed.
151 */
152 #define KOS_IMG_NOT_OWNER 0x0400
153 
154 /** @} */
155 
156 /** \brief Free a kos_img_t object.
157 
158  This function frees the data in a kos_img_t object, returning any memory to
159  the heap as appropriate. Optionally, this can also free the object itself,
160  if required.
161 
162  \param img The image object to free.
163  \param struct_also Set to non-zero to free the image object itself,
164  as well as any data contained therein.
165 */
166 void kos_img_free(kos_img_t *img, int struct_also);
167 
168 __END_DECLS
169 
170 #endif /* __KOS_IMG_H */
171 
uint32 byte_count
Length of the image data, in bytes.
Definition: img.h:51
uint32 h
Height of the image.
Definition: img.h:47
Common integer types.
uint32 fmt
Format of the image data.
Definition: img.h:48
void * data
Image data in the specified format.
Definition: img.h:45
Platform-indpendent image type.
Definition: img.h:44
uint32 w
Width of the image.
Definition: img.h:46
unsigned long uint32
32-bit unsigned integer
Definition: types.h:28
void kos_img_free(kos_img_t *img, int struct_also)
Free a kos_img_t object.
struct kos_img kos_img_t
Platform-indpendent image type.