帧缓冲设备 API¶

最后修订：2011 年 6 月 21 日

0. 简介¶

本文档描述了应用程序用于与帧缓冲设备交互的帧缓冲 API。本文档不描述设备驱动程序和帧缓冲核心之间的内核 API。

由于原始帧缓冲 API 中缺少文档，驱动程序的行为在细微（和不那么细微）的方面有所不同。本文档描述了推荐的 API 实现，但应用程序应准备好处理不同的行为。

1. 功能¶

设备和驱动程序的功能在固定屏幕信息功能字段中报告

struct fb_fix_screeninfo {
      ...
      __u16 capabilities;             /* see FB_CAP_*                 */
      ...
};

应用程序应使用这些功能来了解它们可以从设备和驱动程序中获得哪些功能。

FB_CAP_FOURCC

驱动程序支持基于四字符代码 (FOURCC) 的格式设置 API。当支持时，格式是使用 FOURCC 而不是手动指定颜色分量布局来配置的。

2. 类型和视觉效果¶

像素以硬件相关的格式存储在内存中。应用程序需要了解像素存储格式，以便以硬件期望的格式将图像数据写入帧缓冲内存。

格式由帧缓冲类型和视觉效果描述。某些视觉效果需要额外的信息，这些信息存储在可变屏幕信息 bits_per_pixel、grayscale、red、green、blue 和 transp 字段中。

视觉效果描述如何编码和组装颜色信息以创建宏像素。类型描述宏像素在内存中的存储方式。支持以下类型和视觉效果。

FB_TYPE_PACKED_PIXELS

宏像素在单个平面中连续存储。如果每个宏像素的位数不是 8 的倍数，则宏像素是否填充到下一个 8 位倍数或打包到字节中取决于视觉效果。

行尾可能存在填充，然后通过固定屏幕信息 line_length 字段报告。

FB_TYPE_PLANES

宏像素在多个平面上分割。平面的数量等于每个宏像素的位数，平面 i 存储来自所有宏像素的第 i 位。

平面在内存中连续放置。

FB_TYPE_INTERLEAVED_PLANES

宏像素在多个平面上分割。平面的数量等于每个宏像素的位数，平面 i 存储来自所有宏像素的第 i 位。

平面在内存中交错。交错因子定义为属于不同平面的两个连续交错块的开头之间的字节距离，存储在固定屏幕信息 type_aux 字段中。

FB_TYPE_FOURCC

宏像素按照可变屏幕信息 grayscale 字段中存储的格式 FOURCC 标识符描述的方式存储在内存中。

FB_VISUAL_MONO01

像素为黑色或白色，并存储在可变屏幕信息 bpp 字段指定的位数（通常为一个）上。

黑色像素由所有位设置为 1 表示，白色像素由所有位设置为 0 表示。当每个像素的位数小于 8 时，多个像素打包到一个字节中。

FB_VISUAL_MONO01 当前仅与 FB_TYPE_PACKED_PIXELS 一起使用。

FB_VISUAL_MONO10

像素为黑色或白色，并存储在可变屏幕信息 bpp 字段指定的位数（通常为一个）上。

黑色像素由所有位设置为 0 表示，白色像素由所有位设置为 1 表示。当每个像素的位数小于 8 时，多个像素打包到一个字节中。

FB_VISUAL_MONO01 当前仅与 FB_TYPE_PACKED_PIXELS 一起使用。

FB_VISUAL_TRUECOLOR

像素被分解为红色、绿色和蓝色分量，每个分量都索引一个只读查找表以获取相应的值。查找表是与设备相关的，并提供线性或非线性斜坡。

每个分量都根据可变屏幕信息 red、green、blue 和 transp 字段存储在宏像素中。

FB_VISUAL_PSEUDOCOLOR 和 FB_VISUAL_STATIC_PSEUDOCOLOR

像素值被编码为存储红色、绿色和蓝色分量的颜色映射的索引。颜色映射对于 FB_VISUAL_STATIC_PSEUDOCOLOR 是只读的，对于 FB_VISUAL_PSEUDOCOLOR 是可读写的。

每个像素值存储在可变屏幕信息 bits_per_pixel 字段报告的位数中。

FB_VISUAL_DIRECTCOLOR

像素被分解为红色、绿色和蓝色分量，每个分量都索引一个可编程查找表以获取相应的值。

每个分量都根据可变屏幕信息 red、green、blue 和 transp 字段存储在宏像素中。

FB_VISUAL_FOURCC

像素按照可变屏幕信息 grayscale 字段中存储的格式 FOURCC 标识符描述的方式进行编码和解释。

3. 屏幕信息¶

屏幕信息由应用程序使用 FBIOGET_FSCREENINFO 和 FBIOGET_VSCREENINFO ioctl 查询。这些 ioctl 分别采用指向 fb_fix_screeninfo 和 fb_var_screeninfo 结构的指针。

struct fb_fix_screeninfo 存储有关帧缓冲设备和当前格式的设备无关的不可更改信息。这些信息不能由应用程序直接修改，但当应用程序修改格式时，驱动程序可以更改这些信息

struct fb_fix_screeninfo {
      char id[16];                    /* identification string eg "TT Builtin" */
      unsigned long smem_start;       /* Start of frame buffer mem */
                                      /* (physical address) */
      __u32 smem_len;                 /* Length of frame buffer mem */
      __u32 type;                     /* see FB_TYPE_*                */
      __u32 type_aux;                 /* Interleave for interleaved Planes */
      __u32 visual;                   /* see FB_VISUAL_*              */
      __u16 xpanstep;                 /* zero if no hardware panning  */
      __u16 ypanstep;                 /* zero if no hardware panning  */
      __u16 ywrapstep;                /* zero if no hardware ywrap    */
      __u32 line_length;              /* length of a line in bytes    */
      unsigned long mmio_start;       /* Start of Memory Mapped I/O   */
                                      /* (physical address) */
      __u32 mmio_len;                 /* Length of Memory Mapped I/O  */
      __u32 accel;                    /* Indicate to driver which     */
                                      /*  specific chip/card we have  */
      __u16 capabilities;             /* see FB_CAP_*                 */
      __u16 reserved[2];              /* Reserved for future compatibility */
};

struct fb_var_screeninfo 存储有关帧缓冲设备、其当前格式和视频模式以及其他杂项参数的设备无关的可更改信息

struct fb_var_screeninfo {
      __u32 xres;                     /* visible resolution           */
      __u32 yres;
      __u32 xres_virtual;             /* virtual resolution           */
      __u32 yres_virtual;
      __u32 xoffset;                  /* offset from virtual to visible */
      __u32 yoffset;                  /* resolution                   */

      __u32 bits_per_pixel;           /* guess what                   */
      __u32 grayscale;                /* 0 = color, 1 = grayscale,    */
                                      /* >1 = FOURCC                  */
      struct fb_bitfield red;         /* bitfield in fb mem if true color, */
      struct fb_bitfield green;       /* else only length is significant */
      struct fb_bitfield blue;
      struct fb_bitfield transp;      /* transparency                 */

      __u32 nonstd;                   /* != 0 Non standard pixel format */

      __u32 activate;                 /* see FB_ACTIVATE_*            */

      __u32 height;                   /* height of picture in mm    */
      __u32 width;                    /* width of picture in mm     */

      __u32 accel_flags;              /* (OBSOLETE) see fb_info.flags */

      /* Timing: All values in pixclocks, except pixclock (of course) */
      __u32 pixclock;                 /* pixel clock in ps (pico seconds) */
      __u32 left_margin;              /* time from sync to picture    */
      __u32 right_margin;             /* time from picture to sync    */
      __u32 upper_margin;             /* time from sync to picture    */
      __u32 lower_margin;
      __u32 hsync_len;                /* length of horizontal sync    */
      __u32 vsync_len;                /* length of vertical sync      */
      __u32 sync;                     /* see FB_SYNC_*                */
      __u32 vmode;                    /* see FB_VMODE_*               */
      __u32 rotate;                   /* angle we rotate counter clockwise */
      __u32 colorspace;               /* colorspace for FOURCC-based modes */
      __u32 reserved[4];              /* Reserved for future compatibility */
};

要修改可变信息，应用程序会使用指向 fb_var_screeninfo 结构的指针调用 FBIOPUT_VSCREENINFO ioctl。如果调用成功，驱动程序将相应地更新固定屏幕信息。

应用程序不应手动填充完整的 fb_var_screeninfo 结构，而应调用 FBIOGET_VSCREENINFO ioctl，并且仅修改它们关心的字段。

4. 格式配置¶

帧缓冲设备提供两种配置帧缓冲格式的方法：旧式 API 和基于 FOURCC 的 API。

旧式 API 长期以来一直是唯一的帧缓冲格式配置 API，因此被应用程序广泛使用。当使用 RGB 和灰度格式以及旧式非标准格式时，它是应用程序推荐的 API。

要选择格式，应用程序将 fb_var_screeninfo bits_per_pixel 字段设置为所需的帧缓冲深度。最大 8 的值通常会映射到单色、灰度或伪彩色视觉效果，尽管这不是必需的。

对于灰度格式，应用程序将 grayscale 字段设置为 1。应用程序必须将 red、blue、green 和 transp 字段设置为 0，驱动程序会忽略这些字段。驱动程序必须将 red、blue 和 green 偏移量填充为 0，将长度填充为 bits_per_pixel 值。
对于伪彩色格式，应用程序将 grayscale 字段设置为 0。应用程序必须将 red、blue、green 和 transp 字段设置为 0，驱动程序会忽略这些字段。驱动程序必须将 red、blue 和 green 偏移量填充为 0，将长度填充为 bits_per_pixel 值。
对于真彩色和直接彩色格式，应用程序将 grayscale 字段设置为 0，并将 red、blue、green 和 transp 字段设置为描述内存中颜色分量的布局
```
struct fb_bitfield {
    __u32 offset;                   /* beginning of bitfield        */
    __u32 length;                   /* length of bitfield           */
    __u32 msb_right;                /* != 0 : Most significant bit is */
                                    /* right */
};
```
像素值是 bits_per_pixel 宽的，并被分割为不重叠的红色、绿色、蓝色和 alpha（透明度）分量。像素值中每个分量的位置和大小由 fb_bitfield offset 和 length 字段描述。偏移量从右侧计算。

像素始终以整数个字节存储。如果每个像素的位数不是 8 的倍数，则像素值将填充到下一个 8 位倍数。

成功配置格式后，驱动程序将根据所选格式更新 fb_fix_screeninfo type、visual 和 line_length 字段。

基于 FOURCC 的 API 用四字符代码 (FOURCC) 替换格式描述。FOURCC 是抽象标识符，它们唯一地定义了一种格式，而无需显式描述它。这是唯一支持 YUV 格式的 API。还鼓励驱动程序为 RGB 和灰度格式实现基于 FOURCC 的 API。

支持基于 FOURCC 的 API 的驱动程序通过设置 fb_fix_screeninfo capabilities 字段中的 FB_CAP_FOURCC 位来报告此功能。

FOURCC 定义位于 linux/videodev2.h 标头中。然而，尽管以 V4L2_PIX_FMT_ 前缀开头，但它们并不限于 V4L2，也不需要使用 V4L2 子系统。FOURCC 文档可在图像格式中找到。

要选择格式，应用程序将 grayscale 字段设置为所需的 FOURCC。对于 YUV 格式，它们还应通过将 colorspace 字段设置为 linux/videodev2.h 中列出的颜色空间之一并在颜色空间中记录的颜色空间之一来选择适当的颜色空间。

red、green、blue 和 transp 字段不与基于 FOURCC 的 API 一起使用。出于向前兼容性的原因，应用程序必须将这些字段清零，驱动程序必须忽略它们。除 0 以外的值可能会在未来的扩展中获得含义。

成功配置格式后，驱动程序将根据所选格式更新 fb_fix_screeninfo type、visual 和 line_length 字段。type 和 visual 字段分别设置为 FB_TYPE_FOURCC 和 FB_VISUAL_FOURCC。

Linux 内核

目录

本页