| 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 used by applications to interact
|
| 12 | with frame buffer devices. In-kernel APIs between device drivers and the frame
|
| 13 | buffer core are not described.
|
| 14 |
|
| 15 | Due to a lack of documentation in the original frame buffer API, drivers
|
| 16 | behaviours differ in subtle (and not so subtle) ways. This document describes
|
| 17 | the recommended API implementation, but applications should be prepared to
|
| 18 | deal with different behaviours.
|
| 19 |
|
| 20 |
|
| 21 | 1. Capabilities
|
| 22 | ---------------
|
| 23 |
|
| 24 | Device and driver capabilities are reported in the fixed screen information
|
| 25 | capabilities field::
|
| 26 |
|
| 27 | struct fb_fix_screeninfo {
|
| 28 | ...
|
| 29 | __u16 capabilities; /* see FB_CAP_* */
|
| 30 | ...
|
| 31 | };
|
| 32 |
|
| 33 | Application should use those capabilities to find out what features they can
|
| 34 | expect from the device and driver.
|
| 35 |
|
| 36 | - FB_CAP_FOURCC
|
| 37 |
|
| 38 | The driver supports the four character code (FOURCC) based format setting API.
|
| 39 | When supported, formats are configured using a FOURCC instead of manually
|
| 40 | specifying color components layout.
|
| 41 |
|
| 42 |
|
| 43 | 2. Types and visuals
|
| 44 | --------------------
|
| 45 |
|
| 46 | Pixels are stored in memory in hardware-dependent formats. Applications need
|
| 47 | to be aware of the pixel storage format in order to write image data to the
|
| 48 | frame buffer memory in the format expected by the hardware.
|
| 49 |
|
| 50 | Formats are described by frame buffer types and visuals. Some visuals require
|
| 51 | additional information, which are stored in the variable screen information
|
| 52 | bits_per_pixel, grayscale, red, green, blue and transp fields.
|
| 53 |
|
| 54 | Visuals describe how color information is encoded and assembled to create
|
| 55 | macropixels. Types describe how macropixels are stored in memory. The following
|
| 56 | types and visuals are supported.
|
| 57 |
|
| 58 | - FB_TYPE_PACKED_PIXELS
|
| 59 |
|
| 60 | Macropixels are stored contiguously in a single plane. If the number of bits
|
| 61 | per macropixel is not a multiple of 8, whether macropixels are padded to the
|
| 62 | next multiple of 8 bits or packed together into bytes depends on the visual.
|
| 63 |
|
| 64 | Padding at end of lines may be present and is then reported through the fixed
|
| 65 | screen information line_length field.
|
| 66 |
|
| 67 | - FB_TYPE_PLANES
|
| 68 |
|
| 69 | Macropixels are split across multiple planes. The number of planes is equal to
|
| 70 | the number of bits per macropixel, with plane i'th storing i'th bit from all
|
| 71 | macropixels.
|
| 72 |
|
| 73 | Planes are located contiguously in memory.
|
| 74 |
|
| 75 | - FB_TYPE_INTERLEAVED_PLANES
|
| 76 |
|
| 77 | Macropixels are split across multiple planes. The number of planes is equal to
|
| 78 | the number of bits per macropixel, with plane i'th storing i'th bit from all
|
| 79 | macropixels.
|
| 80 |
|
| 81 | Planes are interleaved in memory. The interleave factor, defined as the
|
| 82 | distance in bytes between the beginning of two consecutive interleaved blocks
|
| 83 | belonging to different planes, is stored in the fixed screen information
|
| 84 | type_aux field.
|
| 85 |
|
| 86 | - FB_TYPE_FOURCC
|
| 87 |
|
| 88 | Macropixels are stored in memory as described by the format FOURCC identifier
|
| 89 | stored in the variable screen information grayscale field.
|
| 90 |
|
| 91 | - FB_VISUAL_MONO01
|
| 92 |
|
| 93 | Pixels are black or white and stored on a number of bits (typically one)
|
| 94 | specified by the variable screen information bpp field.
|
| 95 |
|
| 96 | Black pixels are represented by all bits set to 1 and white pixels by all bits
|
| 97 | set to 0. When the number of bits per pixel is smaller than 8, several pixels
|
| 98 | are packed together in a byte.
|
| 99 |
|
| 100 | FB_VISUAL_MONO01 is currently used with FB_TYPE_PACKED_PIXELS only.
|
| 101 |
|
| 102 | - FB_VISUAL_MONO10
|
| 103 |
|
| 104 | Pixels are black or white and stored on a number of bits (typically one)
|
| 105 | specified by the variable screen information bpp field.
|
| 106 |
|
| 107 | Black pixels are represented by all bits set to 0 and white pixels by all bits
|
| 108 | set to 1. When the number of bits per pixel is smaller than 8, several pixels
|
| 109 | are packed together in a byte.
|
| 110 |
|
| 111 | FB_VISUAL_MONO01 is currently used with FB_TYPE_PACKED_PIXELS only.
|
| 112 |
|
| 113 | - FB_VISUAL_TRUECOLOR
|
| 114 |
|
| 115 | Pixels are broken into red, green and blue components, and each component
|
| 116 | indexes a read-only lookup table for the corresponding value. Lookup tables
|
| 117 | are device-dependent, and provide linear or non-linear ramps.
|
| 118 |
|
| 119 | Each component is stored in a macropixel according to the variable screen
|
| 120 | information red, green, blue and transp fields.
|
| 121 |
|
| 122 | - FB_VISUAL_PSEUDOCOLOR and FB_VISUAL_STATIC_PSEUDOCOLOR
|
| 123 |
|
| 124 | Pixel values are encoded as indices into a colormap that stores red, green and
|
| 125 | blue components. The colormap is read-only for FB_VISUAL_STATIC_PSEUDOCOLOR
|
| 126 | and read-write for FB_VISUAL_PSEUDOCOLOR.
|
| 127 |
|
| 128 | Each pixel value is stored in the number of bits reported by the variable
|
| 129 | screen information bits_per_pixel field.
|
| 130 |
|
| 131 | - FB_VISUAL_DIRECTCOLOR
|
| 132 |
|
| 133 | Pixels are broken into red, green and blue components, and each component
|
| 134 | indexes a programmable lookup table for the corresponding value.
|
| 135 |
|
| 136 | Each component is stored in a macropixel according to the variable screen
|
| 137 | information red, green, blue and transp fields.
|
| 138 |
|
| 139 | - FB_VISUAL_FOURCC
|
| 140 |
|
| 141 | Pixels are encoded and interpreted as described by the format FOURCC
|
| 142 | identifier stored in the variable screen information grayscale field.
|
| 143 |
|
| 144 |
|
| 145 | 3. Screen information
|
| 146 | ---------------------
|
| 147 |
|
| 148 | Screen information are queried by applications using the FBIOGET_FSCREENINFO
|
| 149 | and FBIOGET_VSCREENINFO ioctls. Those ioctls take a pointer to a
|
| 150 | fb_fix_screeninfo and fb_var_screeninfo structure respectively.
|
| 151 |
|
| 152 | struct fb_fix_screeninfo stores device independent unchangeable information
|
| 153 | about the frame buffer device and the current format. Those information can't
|
| 154 | be directly modified by applications, but can be changed by the driver when an
|
| 155 | application modifies the format::
|
| 156 |
|
| 157 | struct fb_fix_screeninfo {
|
| 158 | char id[16]; /* identification string eg "TT Builtin" */
|
| 159 | unsigned long smem_start; /* Start of frame buffer mem */
|
| 160 | /* (physical address) */
|
| 161 | __u32 smem_len; /* Length of frame buffer mem */
|
| 162 | __u32 type; /* see FB_TYPE_* */
|
| 163 | __u32 type_aux; /* Interleave for interleaved Planes */
|
| 164 | __u32 visual; /* see FB_VISUAL_* */
|
| 165 | __u16 xpanstep; /* zero if no hardware panning */
|
| 166 | __u16 ypanstep; /* zero if no hardware panning */
|
| 167 | __u16 ywrapstep; /* zero if no hardware ywrap */
|
| 168 | __u32 line_length; /* length of a line in bytes */
|
| 169 | unsigned long mmio_start; /* Start of Memory Mapped I/O */
|
| 170 | /* (physical address) */
|
| 171 | __u32 mmio_len; /* Length of Memory Mapped I/O */
|
| 172 | __u32 accel; /* Indicate to driver which */
|
| 173 | /* specific chip/card we have */
|
| 174 | __u16 capabilities; /* see FB_CAP_* */
|
| 175 | __u16 reserved[2]; /* Reserved for future compatibility */
|
| 176 | };
|
| 177 |
|
| 178 | struct fb_var_screeninfo stores device independent changeable information
|
| 179 | about a frame buffer device, its current format and video mode, as well as
|
| 180 | other miscellaneous parameters::
|
| 181 |
|
| 182 | struct fb_var_screeninfo {
|
| 183 | __u32 xres; /* visible resolution */
|
| 184 | __u32 yres;
|
| 185 | __u32 xres_virtual; /* virtual resolution */
|
| 186 | __u32 yres_virtual;
|
| 187 | __u32 xoffset; /* offset from virtual to visible */
|
| 188 | __u32 yoffset; /* resolution */
|
| 189 |
|
| 190 | __u32 bits_per_pixel; /* guess what */
|
| 191 | __u32 grayscale; /* 0 = color, 1 = grayscale, */
|
| 192 | /* >1 = FOURCC */
|
| 193 | struct fb_bitfield red; /* bitfield in fb mem if true color, */
|
| 194 | struct fb_bitfield green; /* else only length is significant */
|
| 195 | struct fb_bitfield blue;
|
| 196 | struct fb_bitfield transp; /* transparency */
|
| 197 |
|
| 198 | __u32 nonstd; /* != 0 Non standard pixel format */
|
| 199 |
|
| 200 | __u32 activate; /* see FB_ACTIVATE_* */
|
| 201 |
|
| 202 | __u32 height; /* height of picture in mm */
|
| 203 | __u32 width; /* width of picture in mm */
|
| 204 |
|
| 205 | __u32 accel_flags; /* (OBSOLETE) see fb_info.flags */
|
| 206 |
|
| 207 | /* Timing: All values in pixclocks, except pixclock (of course) */
|
| 208 | __u32 pixclock; /* pixel clock in ps (pico seconds) */
|
| 209 | __u32 left_margin; /* time from sync to picture */
|
| 210 | __u32 right_margin; /* time from picture to sync */
|
| 211 | __u32 upper_margin; /* time from sync to picture */
|
| 212 | __u32 lower_margin;
|
| 213 | __u32 hsync_len; /* length of horizontal sync */
|
| 214 | __u32 vsync_len; /* length of vertical sync */
|
| 215 | __u32 sync; /* see FB_SYNC_* */
|
| 216 | __u32 vmode; /* see FB_VMODE_* */
|
| 217 | __u32 rotate; /* angle we rotate counter clockwise */
|
| 218 | __u32 colorspace; /* colorspace for FOURCC-based modes */
|
| 219 | __u32 reserved[4]; /* Reserved for future compatibility */
|
| 220 | };
|
| 221 |
|
| 222 | To modify variable information, applications call the FBIOPUT_VSCREENINFO
|
| 223 | ioctl with a pointer to a fb_var_screeninfo structure. If the call is
|
| 224 | successful, the driver will update the fixed screen information accordingly.
|
| 225 |
|
| 226 | Instead of filling the complete fb_var_screeninfo structure manually,
|
| 227 | applications should call the FBIOGET_VSCREENINFO ioctl and modify only the
|
| 228 | fields they care about.
|
| 229 |
|
| 230 |
|
| 231 | 4. Format configuration
|
| 232 | -----------------------
|
| 233 |
|
| 234 | Frame buffer devices offer two ways to configure the frame buffer format: the
|
| 235 | legacy API and the FOURCC-based API.
|
| 236 |
|
| 237 |
|
| 238 | The legacy API has been the only frame buffer format configuration API for a
|
| 239 | long time and is thus widely used by application. It is the recommended API
|
| 240 | for applications when using RGB and grayscale formats, as well as legacy
|
| 241 | non-standard formats.
|
| 242 |
|
| 243 | To select a format, applications set the fb_var_screeninfo bits_per_pixel field
|
| 244 | to the desired frame buffer depth. Values up to 8 will usually map to
|
| 245 | monochrome, grayscale or pseudocolor visuals, although this is not required.
|
| 246 |
|
| 247 | - For grayscale formats, applications set the grayscale field to one. The red,
|
| 248 | blue, green and transp fields must be set to 0 by applications and ignored by
|
| 249 | drivers. Drivers must fill the red, blue and green offsets to 0 and lengths
|
| 250 | to the bits_per_pixel value.
|
| 251 |
|
| 252 | - For pseudocolor formats, applications set the grayscale field to zero. The
|
| 253 | red, blue, green and transp fields must be set to 0 by applications and
|
| 254 | ignored by drivers. Drivers must fill the red, blue and green offsets to 0
|
| 255 | and lengths to the bits_per_pixel value.
|
| 256 |
|
| 257 | - For truecolor and directcolor formats, applications set the grayscale field
|
| 258 | to zero, and the red, blue, green and transp fields to describe the layout of
|
| 259 | color components in memory::
|
| 260 |
|
| 261 | struct fb_bitfield {
|
| 262 | __u32 offset; /* beginning of bitfield */
|
| 263 | __u32 length; /* length of bitfield */
|
| 264 | __u32 msb_right; /* != 0 : Most significant bit is */
|
| 265 | /* right */
|
| 266 | };
|
| 267 |
|
| 268 | Pixel values are bits_per_pixel wide and are split in non-overlapping red,
|
| 269 | green, blue and alpha (transparency) components. Location and size of each
|
| 270 | component in the pixel value are described by the fb_bitfield offset and
|
| 271 | length fields. Offset are computed from the right.
|
| 272 |
|
| 273 | Pixels are always stored in an integer number of bytes. If the number of
|
| 274 | bits per pixel is not a multiple of 8, pixel values are padded to the next
|
| 275 | multiple of 8 bits.
|
| 276 |
|
| 277 | Upon successful format configuration, drivers update the fb_fix_screeninfo
|
| 278 | type, visual and line_length fields depending on the selected format.
|
| 279 |
|
| 280 |
|
| 281 | The FOURCC-based API replaces format descriptions by four character codes
|
| 282 | (FOURCC). FOURCCs are abstract identifiers that uniquely define a format
|
| 283 | without explicitly describing it. This is the only API that supports YUV
|
| 284 | formats. Drivers are also encouraged to implement the FOURCC-based API for RGB
|
| 285 | and grayscale formats.
|
| 286 |
|
| 287 | Drivers that support the FOURCC-based API report this capability by setting
|
| 288 | the FB_CAP_FOURCC bit in the fb_fix_screeninfo capabilities field.
|
| 289 |
|
| 290 | FOURCC definitions are located in the linux/videodev2.h header. However, and
|
| 291 | despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2
|
| 292 | and don't require usage of the V4L2 subsystem. FOURCC documentation is
|
| 293 | available in Documentation/userspace-api/media/v4l/pixfmt.rst.
|
| 294 |
|
| 295 | To select a format, applications set the grayscale field to the desired FOURCC.
|
| 296 | For YUV formats, they should also select the appropriate colorspace by setting
|
| 297 | the colorspace field to one of the colorspaces listed in linux/videodev2.h and
|
| 298 | documented in Documentation/userspace-api/media/v4l/colorspaces.rst.
|
| 299 |
|
| 300 | The red, green, blue and transp fields are not used with the FOURCC-based API.
|
| 301 | For forward compatibility reasons applications must zero those fields, and
|
| 302 | drivers must ignore them. Values other than 0 may get a meaning in future
|
| 303 | extensions.
|
| 304 |
|
| 305 | Upon successful format configuration, drivers update the fb_fix_screeninfo
|
| 306 | type, visual and line_length fields depending on the selected format. The type
|
| 307 | and visual fields are set to FB_TYPE_FOURCC and FB_VISUAL_FOURCC respectively.
|