幀緩衝區裝置 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 核心

目錄

本頁