1 ===========================
2 The Frame Buffer Device API
3 ===========================
4
5 Last revised: June 21, 2011
6
7
8 0. Introduction
9 ---------------
10
11 This document describes the frame buffer API u
12 with frame buffer devices. In-kernel APIs betw
13 buffer core are not described.
14
15 Due to a lack of documentation in the original
16 behaviours differ in subtle (and not so subtle
17 the recommended API implementation, but applic
18 deal with different behaviours.
19
20
21 1. Capabilities
22 ---------------
23
24 Device and driver capabilities are reported in
25 capabilities field::
26
27 struct fb_fix_screeninfo {
28 ...
29 __u16 capabilities; /* see
30 ...
31 };
32
33 Application should use those capabilities to f
34 expect from the device and driver.
35
36 - FB_CAP_FOURCC
37
38 The driver supports the four character code (F
39 When supported, formats are configured using a
40 specifying color components layout.
41
42
43 2. Types and visuals
44 --------------------
45
46 Pixels are stored in memory in hardware-depend
47 to be aware of the pixel storage format in ord
48 frame buffer memory in the format expected by
49
50 Formats are described by frame buffer types an
51 additional information, which are stored in th
52 bits_per_pixel, grayscale, red, green, blue an
53
54 Visuals describe how color information is enco
55 macropixels. Types describe how macropixels ar
56 types and visuals are supported.
57
58 - FB_TYPE_PACKED_PIXELS
59
60 Macropixels are stored contiguously in a singl
61 per macropixel is not a multiple of 8, whether
62 next multiple of 8 bits or packed together int
63
64 Padding at end of lines may be present and is
65 screen information line_length field.
66
67 - FB_TYPE_PLANES
68
69 Macropixels are split across multiple planes.
70 the number of bits per macropixel, with plane
71 macropixels.
72
73 Planes are located contiguously in memory.
74
75 - FB_TYPE_INTERLEAVED_PLANES
76
77 Macropixels are split across multiple planes.
78 the number of bits per macropixel, with plane
79 macropixels.
80
81 Planes are interleaved in memory. The interlea
82 distance in bytes between the beginning of two
83 belonging to different planes, is stored in th
84 type_aux field.
85
86 - FB_TYPE_FOURCC
87
88 Macropixels are stored in memory as described
89 stored in the variable screen information gray
90
91 - FB_VISUAL_MONO01
92
93 Pixels are black or white and stored on a numb
94 specified by the variable screen information b
95
96 Black pixels are represented by all bits set t
97 set to 0. When the number of bits per pixel is
98 are packed together in a byte.
99
100 FB_VISUAL_MONO01 is currently used with FB_TYP
101
102 - FB_VISUAL_MONO10
103
104 Pixels are black or white and stored on a numb
105 specified by the variable screen information b
106
107 Black pixels are represented by all bits set t
108 set to 1. When the number of bits per pixel is
109 are packed together in a byte.
110
111 FB_VISUAL_MONO01 is currently used with FB_TYP
112
113 - FB_VISUAL_TRUECOLOR
114
115 Pixels are broken into red, green and blue com
116 indexes a read-only lookup table for the corre
117 are device-dependent, and provide linear or no
118
119 Each component is stored in a macropixel accor
120 information red, green, blue and transp fields
121
122 - FB_VISUAL_PSEUDOCOLOR and FB_VISUAL_STATIC_P
123
124 Pixel values are encoded as indices into a col
125 blue components. The colormap is read-only for
126 and read-write for FB_VISUAL_PSEUDOCOLOR.
127
128 Each pixel value is stored in the number of bi
129 screen information bits_per_pixel field.
130
131 - FB_VISUAL_DIRECTCOLOR
132
133 Pixels are broken into red, green and blue com
134 indexes a programmable lookup table for the co
135
136 Each component is stored in a macropixel accor
137 information red, green, blue and transp fields
138
139 - FB_VISUAL_FOURCC
140
141 Pixels are encoded and interpreted as describ
142 identifier stored in the variable screen infor
143
144
145 3. Screen information
146 ---------------------
147
148 Screen information are queried by applications
149 and FBIOGET_VSCREENINFO ioctls. Those ioctls t
150 fb_fix_screeninfo and fb_var_screeninfo struct
151
152 struct fb_fix_screeninfo stores device indepen
153 about the frame buffer device and the current
154 be directly modified by applications, but can
155 application modifies the format::
156
157 struct fb_fix_screeninfo {
158 char id[16]; /* ide
159 unsigned long smem_start; /* Sta
160 /* (ph
161 __u32 smem_len; /* Len
162 __u32 type; /* see
163 __u32 type_aux; /* Int
164 __u32 visual; /* see
165 __u16 xpanstep; /* zer
166 __u16 ypanstep; /* zer
167 __u16 ywrapstep; /* zer
168 __u32 line_length; /* len
169 unsigned long mmio_start; /* Sta
170 /* (ph
171 __u32 mmio_len; /* Len
172 __u32 accel; /* Ind
173 /* sp
174 __u16 capabilities; /* see
175 __u16 reserved[2]; /* Res
176 };
177
178 struct fb_var_screeninfo stores device indepen
179 about a frame buffer device, its current forma
180 other miscellaneous parameters::
181
182 struct fb_var_screeninfo {
183 __u32 xres; /* vis
184 __u32 yres;
185 __u32 xres_virtual; /* vir
186 __u32 yres_virtual;
187 __u32 xoffset; /* off
188 __u32 yoffset; /* res
189
190 __u32 bits_per_pixel; /* gue
191 __u32 grayscale; /* 0 =
192 /* >1
193 struct fb_bitfield red; /* bit
194 struct fb_bitfield green; /* els
195 struct fb_bitfield blue;
196 struct fb_bitfield transp; /* tra
197
198 __u32 nonstd; /* !=
199
200 __u32 activate; /* see
201
202 __u32 height; /* hei
203 __u32 width; /* wid
204
205 __u32 accel_flags; /* (OB
206
207 /* Timing: All values in pixclocks, ex
208 __u32 pixclock; /* pix
209 __u32 left_margin; /* tim
210 __u32 right_margin; /* tim
211 __u32 upper_margin; /* tim
212 __u32 lower_margin;
213 __u32 hsync_len; /* len
214 __u32 vsync_len; /* len
215 __u32 sync; /* see
216 __u32 vmode; /* see
217 __u32 rotate; /* ang
218 __u32 colorspace; /* col
219 __u32 reserved[4]; /* Res
220 };
221
222 To modify variable information, applications c
223 ioctl with a pointer to a fb_var_screeninfo st
224 successful, the driver will update the fixed s
225
226 Instead of filling the complete fb_var_screeni
227 applications should call the FBIOGET_VSCREENIN
228 fields they care about.
229
230
231 4. Format configuration
232 -----------------------
233
234 Frame buffer devices offer two ways to configu
235 legacy API and the FOURCC-based API.
236
237
238 The legacy API has been the only frame buffer
239 long time and is thus widely used by applicati
240 for applications when using RGB and grayscale
241 non-standard formats.
242
243 To select a format, applications set the fb_va
244 to the desired frame buffer depth. Values up t
245 monochrome, grayscale or pseudocolor visuals,
246
247 - For grayscale formats, applications set the
248 blue, green and transp fields must be set to
249 drivers. Drivers must fill the red, blue and
250 to the bits_per_pixel value.
251
252 - For pseudocolor formats, applications set th
253 red, blue, green and transp fields must be s
254 ignored by drivers. Drivers must fill the re
255 and lengths to the bits_per_pixel value.
256
257 - For truecolor and directcolor formats, appli
258 to zero, and the red, blue, green and transp
259 color components in memory::
260
261 struct fb_bitfield {
262 __u32 offset; /* beg
263 __u32 length; /* len
264 __u32 msb_right; /* !=
265 /* rig
266 };
267
268 Pixel values are bits_per_pixel wide and are
269 green, blue and alpha (transparency) compone
270 component in the pixel value are described b
271 length fields. Offset are computed from the
272
273 Pixels are always stored in an integer numbe
274 bits per pixel is not a multiple of 8, pixel
275 multiple of 8 bits.
276
277 Upon successful format configuration, drivers
278 type, visual and line_length fields depending
279
280
281 The FOURCC-based API replaces format descripti
282 (FOURCC). FOURCCs are abstract identifiers tha
283 without explicitly describing it. This is the
284 formats. Drivers are also encouraged to implem
285 and grayscale formats.
286
287 Drivers that support the FOURCC-based API repo
288 the FB_CAP_FOURCC bit in the fb_fix_screeninfo
289
290 FOURCC definitions are located in the linux/vi
291 despite starting with the V4L2_PIX_FMT_prefix,
292 and don't require usage of the V4L2 subsystem.
293 available in Documentation/userspace-api/media
294
295 To select a format, applications set the grays
296 For YUV formats, they should also select the a
297 the colorspace field to one of the colorspaces
298 documented in Documentation/userspace-api/medi
299
300 The red, green, blue and transp fields are not
301 For forward compatibility reasons applications
302 drivers must ignore them. Values other than 0
303 extensions.
304
305 Upon successful format configuration, drivers
306 type, visual and line_length fields depending
307 and visual fields are set to FB_TYPE_FOURCC an
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.