关于X11 XY格式图像绘制及xcb_put_image函数的技术问询

刚好之前折腾过XCB的像素绘制，来给你详细说说怎么用xcb_put_image实现XY格式的图像渲染～

这个函数是XCB里直接往窗口或像素图写入像素数据的核心工具，先把它的签名拆解清楚：

xcb_void_cookie_t xcb_put_image(
    xcb_connection_t *conn,
    uint8_t format,
    xcb_drawable_t drawable,
    xcb_gcontext_t gc,
    uint16_t width,
    uint16_t height,
    int16_t dst_x,
    int16_t dst_y,
    uint8_t left_pad,
    uint8_t depth,
    uint32_t data_len,
    const uint8_t *data
)

关键参数解析（针对XY格式绘制） #

• conn: 和X服务器通信的核心连接句柄，必须提前完成初始化。
• format: 决定X服务器解析像素数据的规则，XY格式（行优先、从上到下从左到右排列）常用这两个：
  • XCB_IMAGE_FORMAT_Z_PIXMAP: 彩色图像首选格式，像素按连续行存储，注意行对齐要求即可。
  • XCB_IMAGE_FORMAT_X_Y_BITMAP: 仅用于单色位图场景，彩色绘制一般不用。
• drawable: 绘制目标，可以是窗口（xcb_window_t）或像素图（xcb_pixmap_t），需提前创建。
• gc: 图形上下文，控制绘制的前景色、背景色等属性，要先创建并配置好对应颜色映射。
• width/height: 待绘制图像的宽高，单位为像素。
• dst_x/dst_y: 目标drawable上的绘制起始坐标，也就是图像在窗口中的左上角位置。
• left_pad: 每行像素数据开头的填充字节数，用来满足X服务器的4字节对齐要求。如果你的每行像素数据已经对齐，填0即可；不确定的话可以通过(width * depth + 7) / 8计算每行字节数，再补全到4的倍数，差值就是left_pad。
• depth: 像素位深度，比如24位真彩色填24、32位填32，要和data中的像素格式完全匹配。
• data_len: 像素数据缓冲区的总字节数，一般为width * height * (depth / 8)（无额外填充时）。
• data: 存储XY格式像素数据的缓冲区，按行优先排列，每个像素的颜色数据要和depth、format对应（比如24位深度下就是RGB/BGR的连续字节）。

快速上手示例 #

举个简单例子，在窗口的(10,10)位置绘制一个2x2的红色方块（24位深度）：

// 假设已完成conn、window、gc的初始化与配置
uint8_t pixels[] = {
    0xFF, 0x00, 0x00, 0xFF, 0x00, 0x00,  // 第一行两个红色像素
    0xFF, 0x00, 0x00, 0xFF, 0x00, 0x00   // 第二行两个红色像素
};

// 调用绘制函数
xcb_put_image(
    conn,
    XCB_IMAGE_FORMAT_Z_PIXMAP,
    window,
    gc,
    2, 2,          // 图像宽高
    10, 10,        // 窗口内起始坐标
    0,             // 无左填充
    24,            // 24位像素深度
    sizeof(pixels),// 数据总字节数
    pixels
);

// 刷新请求，让X服务器执行绘制操作
xcb_flush(conn);

注意：要确保gc已经设置了正确的颜色映射，真彩色场景下要和X服务器的颜色字节顺序匹配哦～

内容的提问来源于stack exchange，提问作者Bartłomiej Sługocki