帧缓冲区设备 API¶

上次修订时间：2011 年 6 月 21 日

0. 简介¶

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

由于原始帧缓冲区 API 中缺乏文档，因此驱动程序的行为存在细微（并非不细微）的差异。本文档描述了推荐的 API 实现，但应用程序应准备好处理不同的行为。

1. 功能¶

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

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。如果调用成功，驱动程序将相应地更新固定屏幕信息。

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

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 字段设置为零。 red、blue、green 和 transp 字段必须由应用程序设置为 0，并由驱动程序忽略。驱动程序必须将 red、blue 和 green 偏移量填充为 0，并将长度填充为 bits_per_pixel 值。
对于真彩色和直接彩色格式，应用程序将 grayscale 字段设置为零，并将 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 偏移量和长度字段描述。偏移量从右侧计算。

像素始终以整数个字节存储。如果每个像素的位数不是 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_prefix 开头，但它们并不限于 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 内核

目录

本页