Feature: Implement the Linux screen preview response

The Linux client now answers COMMAND_SCREEN_PREVIEW_REQ, so a host with
an X11 desktop gets a thumbnail when it is double-clicked in the online
list, a frame in the list's Preview column, and an image from the MCP
get_screenshot tool. Previously only Windows clients advertised the
capability and Linux hosts showed "预览不可用" after a four second wait.

The client does not encode JPEG. Stock desktops ship libjpeg.so.8 whose
struct layout is the distribution's ABI (JPEG_LIB_VERSION 80), while the
in-tree jpeglib.h is libjpeg-turbo 3.1.1 (62), and libturbojpeg is not
installed by default; dlopening the system library against that header
fails with "Wrong JPEG library version: library is 80, caller expects
62". Instead the client sends raw pixels in a new screen preview format,
SCREEN_PREVIEW_FMT_BGRX: top-down rows of B,G,R,X with no row padding,
already scaled to the requested width. The server re-encodes to JPEG at
the single ingress point, so the preview popup, the list thumbnail cache
and the MCP tool keep consuming JPEG only.

Capture follows the path ScreenHandler already uses: root window copied
into an offscreen pixmap with an IncludeInferiors GC, then XGetImage,
which avoids BadMatch under compositing window managers. The X11 type
declarations and the dlopen loader moved out of ScreenHandler.h into
linux/X11Loader.h so both users share one dlsym table. The full-size
image is never materialized: a box filter reads straight from the
XImage rows (honouring bytes_per_line) into the output buffer, scales to
maxWidth without upscaling, and clamps the height to 1080 so a portrait
4K desktop cannot produce a 26 MB packet. Rows and columns come out
even, which they are for JPEG anyway.

The capability bit is now honest about the runtime. LOGIN_INFOR grows
DefaultCaps()/SetCaps(), and the client recomputes the bits before every
login and re-login: CLIENT_CAP_SCREEN_PREVIEW is set only when DISPLAY is
present and the X server actually opens. A headless host therefore gets
-32005 "Host does not support screen preview" from MCP instead of a
timeout, and a host whose session appears after boot picks it up on the
next reconnect. Requests are handled on a detached worker thread behind
a single-flight guard (matching the Windows client), so a slow XGetImage
never stalls the receive thread and a burst of requests degrades to "no
preview" rather than queueing. If the worker thread cannot be created,
the guard is released again, so one failure cannot leave every later
request rejected as busy until the client restarts.

The MCP design note claimed the capability was declared by Windows only,
and the get_screenshot tool description said the same; both now say what
the code does (Windows always, Linux when a display is reachable).

Server side, NormalizeScreenPreviewPacket runs in MessageHandle before
the MCP handoff and the PostMessage to the UI thread. It validates that
width/height are within the values the server itself can ask for and
that bytes equals width*height*4, converts with a stack Gdiplus::Bitmap
over the packet's own pixels (no copy, and no DEBUG_NEW trouble), and
rewrites the header to JPEG. The encoder output is read back by seeking
the stream rather than GlobalSize, so the packet carries no heap-block
padding after the EOI marker. Malformed packets are dropped; failure
statuses pass through untouched so the existing code can report them.

Tested against a Debug server with the WSL Ubuntu 24.04 build as the
client. get_screenshot returned valid JPEGs at max_width 480 (480x142,
1.7 KB) and 1920 (1920x570, 17.9 KB), repeatably; the list showed a
thumbnail for the GUI client and N/A for a second copy started without
DISPLAY, which also answered -32005. The box filter and the BGRX to JPEG
conversion were checked separately with quadrant fixtures: the browser
over the synthetic B,G,R,X buffer recovers red/green/blue/white in the
right channels and the downscale averages, handles non-integer ratios
and row padding, and rejects 24bpp and upscaling. The captured frames
come out black under WSLg because Xwayland keeps no root pixmap there;
that is the compositor, not this code, and Xorg sessions capture
normally.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-10-29 18:12:15 +01:00
1 parent 5bff9df3fc
commit dc4fd792f6
12 files changed
+704 -276

No files matched your search

+185
View File
@@ -0,0 +1,185 @@
#include "ScreenPreview.h"
#include "X11Loader.h"
#include "common/commands.h"
#include <cstdlib>
#include <cstring>
namespace {
// 一次抓屏独占一条 X 连接:Xlib 的 Display 不是线程安全的,预览在工作线程里跑,
// 不能复用 ScreenHandler 的那条连接;用完即关,避免长驻连接占着 X server 资源。
struct XSession {
X11Loader x11;
Display* dpy = nullptr;
bool Open()
{
// 没有 DISPLAY 必然是纯命令行/无桌面环境,连库都不必加载
const char* display = getenv("DISPLAY");
if (display == nullptr || display[0] == '\0') {
return false;
}
if (!x11.Load() || !x11.CanCapture()) {
return false;
}
// 与 ScreenHandler 一致:忽略 X11 协议错误,由返回值判断失败
x11.pXSetErrorHandler(x11_error_handler);
dpy = x11.pXOpenDisplay(display);
return dpy != nullptr;
}
~XSession()
{
if (dpy) {
x11.pXCloseDisplay(dpy);
}
}
};
// 盒式滤波缩放,直接从 XImage 读到目标缓冲,不保留整屏中间副本。
// 返回 false 表示像素格式不受支持(非 32bpp)。
bool DownscaleBox(const XImage* img, int tw, int th, std::vector<unsigned char>& out)
{
if (img == nullptr || img->bits_per_pixel != 32 || img->bytes_per_line <= 0) {
return false;
}
const int sw = img->width;
const int sh = img->height;
if (sw <= 0 || sh <= 0 || tw <= 0 || th <= 0 || tw > sw || th > sh) {
return false;
}
out.resize((size_t)tw * th * 4);
const unsigned char* base = (const unsigned char*)img->data;
for (int dy = 0; dy < th; dy++) {
// 目标行覆盖的源行区间 [sy0, sy1),区间非空因为 th <= sh
int sy0 = (int)((long long)dy * sh / th);
int sy1 = (int)((long long)(dy + 1) * sh / th);
if (sy1 <= sy0) sy1 = sy0 + 1;
unsigned char* dst = out.data() + (size_t)dy * tw * 4;
for (int dx = 0; dx < tw; dx++) {
int sx0 = (int)((long long)dx * sw / tw);
int sx1 = (int)((long long)(dx + 1) * sw / tw);
if (sx1 <= sx0) sx1 = sx0 + 1;
unsigned int sb = 0, sg = 0, sr = 0;
unsigned int count = 0;
for (int sy = sy0; sy < sy1; sy++) {
// X11 ZPixmap 32bpp 每像素 4 字节,字节序为 B,G,R,X(X 不用);
// 行尾可能有对齐填充,必须按 bytes_per_line 定位
const unsigned char* row = base + (size_t)sy * img->bytes_per_line;
for (int sx = sx0; sx < sx1; sx++) {
const unsigned char* px = row + (size_t)sx * 4;
sb += px[0];
sg += px[1];
sr += px[2];
count++;
}
}
dst[0] = (unsigned char)(sb / count);
dst[1] = (unsigned char)(sg / count);
dst[2] = (unsigned char)(sr / count);
dst[3] = 0xFF;
dst += 4;
}
}
return true;
}
} // namespace
bool ScreenPreview::IsAvailable()
{
XSession session;
if (!session.Open()) {
return false;
}
int screen = session.x11.pXDefaultScreen(session.dpy);
return session.x11.pXDisplayWidth(session.dpy, screen) > 0 &&
session.x11.pXDisplayHeight(session.dpy, screen) > 0;
}
int ScreenPreview::Capture(int maxWidth, std::vector<unsigned char>& out, int& outW, int& outH)
{
outW = 0;
outH = 0;
out.clear();
// 与 Windows 端一致:上限防滥用,下限防止 1 像素宽的退化请求
if (maxWidth < 64) maxWidth = 64;
if (maxWidth > 1920) maxWidth = 1920;
XSession session;
if (!session.Open()) {
return SCREEN_PREVIEW_NOT_SUPPORTED;
}
X11Loader& x11 = session.x11;
Display* dpy = session.dpy;
int screen = x11.pXDefaultScreen(dpy);
int sw = x11.pXDisplayWidth(dpy, screen);
int sh = x11.pXDisplayHeight(dpy, screen);
if (sw <= 0 || sh <= 0) {
return SCREEN_PREVIEW_CAPTURE_FAILED;
}
// 等比缩放到 maxWidth 以内(不放大);再把高度限制在 1080,避免竖屏 4K 这类
// 极端宽高比把 BGRX 包撑到几十 MB(服务端只按宽度提要求,不管比例)
int tw = sw, th = sh;
if (tw > maxWidth) {
th = (int)((long long)sh * maxWidth / sw);
tw = maxWidth;
}
if (th > 1080) {
tw = (int)((long long)tw * 1080 / th);
th = 1080;
}
// 宽高取偶数,便于 JPEG 编码
tw &= ~1;
th &= ~1;
if (tw < 2) tw = 2;
if (th < 2) th = 2;
if (tw > sw) tw = sw;
if (th > sh) th = sh;
// root → 离屏 Pixmap → XGetImage:绕开合成窗口管理器下的 BadMatch
Window root = x11.pXRootWindow(dpy, screen);
int depth = x11.pXDefaultDepth(dpy, screen);
Pixmap pixmap = x11.pXCreatePixmap(dpy, root, (unsigned int)sw, (unsigned int)sh, (unsigned int)depth);
if (pixmap == 0) {
return SCREEN_PREVIEW_CAPTURE_FAILED;
}
XGCValues_LNX gcv;
memset(&gcv, 0, sizeof(gcv));
gcv.subwindow_mode = IncludeInferiors; // 连同子窗口内容一起抓
GC gc = x11.pXCreateGC(dpy, root, GCSubwindowMode, &gcv);
if (gc == nullptr) {
x11.pXFreePixmap(dpy, pixmap);
return SCREEN_PREVIEW_CAPTURE_FAILED;
}
int result = SCREEN_PREVIEW_CAPTURE_FAILED;
x11.pXCopyArea(dpy, root, pixmap, gc, 0, 0, (unsigned int)sw, (unsigned int)sh, 0, 0);
x11.pXSync(dpy, 0); // 等待拷贝完成
// AllPlanes = ~0UL, ZPixmap = 2
XImage* img = x11.pXGetImage(dpy, pixmap, 0, 0, (unsigned int)sw, (unsigned int)sh, ~0UL, 2);
if (img != nullptr) {
if (DownscaleBox(img, tw, th, out)) {
outW = tw;
outH = th;
result = SCREEN_PREVIEW_OK;
} else {
out.clear();
}
x11.pXDestroyImage(img);
}
x11.pXFreeGC(dpy, gc);
x11.pXFreePixmap(dpy, pixmap);
return result;
}