Xlib - C Language X Interface
1. Xlib - C Language X Interface
The X Window System is a network-transparent window system that was designed at MIT.
X Window System 是由 MIT 设计的透明网络窗口系统。
transparent [trænsˈpærənt]：adj. 透明的，显然的，坦率的，易懂的
monochrome [ˈmɒnəkrəʊm]：n. 黑白照片，单色照片，黑白重现，单色复制 adj. 单色的，黑白的
opaque [əʊˈpeɪk]：adj. 不透明的，不传热的，迟钝的 n. 不透明物 vt. 使不透明，使不反光
Xlib - C Language X Interface is a reference guide to the low-level C language interface to the X Window System protocol.
Xlib - C Language X Interface 是 X Window System 协议的低级 C 语言接口的参考指南。
2. DISPLAY variable
strong@foreverstrong:/usr/include/X11$ echo $DISPLAY
:0
strong@foreverstrong:/usr/include/X11$
A display is indicated with a name, for instance:
显示带有名称，例如：
- DISPLAY=
light.uni.verse:0 - DISPLAY=
localhost:4 - DISPLAY=
:0
The display consists of a hostname (such as light.uni.verse and localhost), a colon (:), and a sequence number (such as 0 and 4). The hostname of the display is the name of the computer where the X server runs. An omitted hostname means the local host. The sequence number is usually 0, it can be varied if there are multiple displays connected to one computer.
显示内容由主机名 (例如 light.uni.verse and localhost)，冒号 (:) 和序列号 (例如 0 和 4) 组成。显示的主机名是 X server 运行所在的计算机的名称。省略的主机名表示本地主机。序列号通常为 0，如果有多台显示器连接到一台计算机，则可以更改。
3. XOpenDisplay, XCloseDisplay - connect or disconnect to X server
Display *XOpenDisplay(char *display_name);
int XCloseDisplay(Display *display);
display - Specifies the connection to the X server. - 指定与 X server 的连接。
display_name - Specifies the hardware display name, which determines the display and communications domain to be used. On a POSIX-conformant system, if the display_name is NULL, it defaults to the value of the DISPLAY environment variable. - 指定硬件显示名称，该名称确定要使用的显示和通信域。在符合 POSIX 的系统上，如果 display_name 为 NULL，则默认为 DISPLAY 环境变量的值。
The encoding and interpretation of the display name is implementation dependent. On POSIX-conformant systems, the display name or DISPLAY environment variable can be a string in the format:
display name 的编码和解释取决于实现。在符合 POSIX 的系统上，display name or DISPLAY 环境变量可以是以下格式的字符串：
hostname:number.screen_number
-
hostname- Specifies the name of the host machine on which the display is physically attached. You follow the hostname with either a single colon (:) or a double colon (::).
指定物理连接显示器的主机的名称。您在主机名后加上单冒号(:) 或双冒号 (::)。 -
number- Specifies the number of the display server on that host machine. You may optionally follow this display number with a period (.). A single CPU can have more than one display. Multiple displays are usually numbered starting with zero.
指定该主机上display server的编号。您可以选择在此显示编号后加上句点 (.)。一个 CPU 可以有多个显示器。多个显示通常从零开始编号。 -
screen_number- Specifies the screen to be used on that server. Multiple screens can be controlled by a single X server. Thescreen_numbersets an internal variable that can be accessed by using theDefaultScreen()macro or theXDefaultScreen()function if you are using languages other than C (seeDisplay Macros).
指定要在该服务器上使用的屏幕。单个X服务器可以控制多个屏幕。screen_number设置一个内部变量，如果您使用的是 C 以外的语言，则可以使用DefaultScreen()宏或XDefaultScreen()函数进行访问 (请参见Display Macros)。
For example, the following would specify screen 1 of display 0 on the machine named dual-headed:
dual-headed:0.1
The XOpenDisplay() function returns a Display structure that serves as the connection to the X server and that contains all the information about that X server. If the hostname is a host machine name and a single colon (:) separates the hostname and display number, XOpenDisplay() connects using TCP streams. If the hostname is not specified, Xlib uses whatever it believes is the fastest transport. If the hostname is a host machine name and a double colon (::) separates the hostname and display number, XOpenDisplay() connects using DECnet. A single X server can support any or all of these transport mechanisms simultaneously. A particular Xlib implementation can support many more of these transport mechanisms.
XOpenDisplay() 函数返回一个 Display 结构，该结构用作与 X 服务器的连接，并且包含有关该 X 服务器的所有信息。如果 hostname 是主机名，并且用单个冒号 (:) 分隔 hostname and display number，则 XOpenDisplay() 使用 TCP 流进行连接。如果未指定主机名，则 Xlib 将使用它认为是最快的传输方式。如果 hostname 是主机名，并且双冒号 (::) 分隔了 hostname and display number，则 XOpenDisplay() 使用 DECnet 连接。单个 X 服务器可以同时支持任何或所有这些传输机制。特定的 Xlib 实现可以支持更多此类传输机制。
If successful, XOpenDisplay() returns a pointer to a Display structure, which is defined in X11/Xlib.h. If XOpenDisplay() does not succeed, it returns NULL. After a successful call to XOpenDisplay() all of the screens in the display can be used by the client. The screen number specified in the display_name argument is returned by the DefaultScreen() macro (or the XDefaultScreen() function). You can access elements of the Display and Screen structures only by using the information macros or functions. For information about using macros and functions to obtain information from the Display structure, see Display Macros.
如果成功，则 XOpenDisplay() 返回指向 Display 结构的指针，该结构在 X11/Xlib.h 中定义。如果 XOpenDisplay() 不成功，则返回 NULL。成功调用 XOpenDisplay()后，客户端可以使用显示中的所有屏幕。在 display_name 参数中指定的屏幕号由 DefaultScreen() 宏 (或 XDefaultScreen() 函数) 返回。您只能使用信息宏或函数来访问 Display and Screen 结构的元素。有关使用宏和函数从 Display 结构中获取信息的信息，请参阅 Display Macros。
4. DefaultScreenOfDisplay
DefaultScreenOfDisplay(display)
Screen *XDefaultScreenOfDisplay(display)
Display *display;
display - Specifies the connection to the X server. - 指定与 X server 的连接。
Both return a pointer to the default screen. - 两者均返回指向默认屏幕的指针。
5. DefaultScreen
DefaultScreen(display)
int XDefaultScreen(display)
Display *display;
display - Specifies the connection to the X server. - 指定与 X server 的连接。
Both return the default screen number referenced by the XOpenDisplay() function. This macro or function should be used to retrieve the screen number in applications that will use only a single screen. - 两者均返回 XOpenDisplay() 函数引用的默认 screen number。该宏或函数应用于在仅使用单个屏幕的应用程序中检索 screen number。
6. BlackPixel, WhitePixel
Both BlackPixel() and WhitePixel() can be used in implementing a monochrome application. These pixel values are for permanently allocated entries in the default colormap. The actual RGB (red, green, and blue) values are settable on some screens and, in any case, may not actually be black or white. The names are intended to convey the expected relative intensity of the colors.
BlackPixel() and WhitePixel() 均可用于实现单色应用程序。这些像素值用于默认颜色图中的永久分配条目。实际的 RGB (红色、绿色和蓝色) 值可以在某些屏幕上设置，并且在任何情况下都可能不是黑色或白色。名称旨在传达预期的颜色相对强度。
BlackPixel(display, screen_number)
unsigned long XBlackPixel(display, screen_number)
Display *display;
int screen_number;
display - Specifies the connection to the X server. - 指定与 X server 的连接。
screen_number - Specifies the appropriate screen number on the host server. - 指定主机服务器上的适当 screen number。
Both return the black pixel value for the specified screen. - 两者都返回指定屏幕的黑色像素值。
WhitePixel(display, screen_number)
unsigned long XWhitePixel(display, screen_number)
Display *display;
int screen_number;
display - Specifies the connection to the X server. - 指定与 X server 的连接。
screen_number - Specifies the appropriate screen number on the host server. - 指定主机服务器上的适当 screen number。
Both return the white pixel value for the specified screen. - 两者都返回指定屏幕的白色像素值。
7. undefined reference toXOpenDisplay’`
13:48:23 **** Build of configuration Debug for project DisplayImage ****
make all
Building file: ../src/DisplayImage.cpp
Invoking: GCC C++ Compiler
g++ -std=c++0x -I/usr/local/include -I/usr/local/include/opencv4 -I/usr/local/include/opencv4/opencv2 -O0 -g3 -Wall -c -fmessage-length=0 -MMD -MP -MF"src/DisplayImage.d" -MT"src/DisplayImage.o" -o "src/DisplayImage.o" "../src/DisplayImage.cpp"
Finished building: ../src/DisplayImage.cpp
Building target: DisplayImage
Invoking: GCC C++ Linker
g++ -L/usr/local/lib -o "DisplayImage" ./src/DisplayImage.o -lopencv_core -lopencv_video -lopencv_ml -lopencv_imgproc -lopencv_img_hash -lopencv_flann -lopencv_features2d -lopencv_calib3d -lopencv_dnn -lopencv_dnn_objdetect -lopencv_cvv -lopencv_text -lopencv_datasets -lopencv_aruco -lopencv_bgsegm -lopencv_shape -lopencv_imgcodecs -lopencv_videoio -lopencv_highgui -lopencv_bioinspired
./src/DisplayImage.o: In function `main':
/home/strong/eclipse-work/DisplayImage/Debug/../src/DisplayImage.cpp:26: undefined reference to `XOpenDisplay'
makefile:45: recipe for target 'DisplayImage' failed
collect2: error: ld returned 1 exit status
make: *** [DisplayImage] Error 1
13:48:24 Build Finished (took 726ms)
//============================================================================
// Name : X11/Xlib.h
// Author : Yongqiang Cheng
// Version : Feb 22, 2020
// Copyright : Copyright (c) 2019 Yongqiang Cheng
// Description : Hello World in C++, Ansi-style
//============================================================================
#include <iostream>
#include <X11/Xlib.h>
using namespace std;
int main(int argc, char** argv)
{
int screen_num(0);
int width(0);
int height(0);
unsigned long background(0);
unsigned long border(0);
Display *x11_info;
Screen *screen_info;
/* First connect to the display server. */
x11_info = XOpenDisplay(NULL);
if (!x11_info)
{
cerr << "Unable to connect to display" << endl;
return 1;
}
screen_info = DefaultScreenOfDisplay(x11_info);
height = screen_info->height;
width = screen_info->width;
/* These are macros that pull useful data out of the display object. */
/* We use these bits of info enough to want them in their own variables. */
screen_num = DefaultScreen(x11_info);
background = BlackPixel(x11_info, screen_num);
border = WhitePixel(x11_info, screen_num);
cout << "the height of the screen in pixels: " << height << endl;
cout << "the width of the screen in pixels: " << width << endl;
cout << "the black pixel value for the specified screen: " << background << endl;
cout << "the white pixel value for the specified screen: " << border << endl;
cout << "the default screen number referenced by the XOpenDisplay() function: " << screen_num << endl;
return 0;
}
Project -> properties -> C/C++ Build -> Settings -> Tool Settings -> GCC C++ Linker -> Libraries (-l) 添加 X11 参数。
13:59:14 **** Build of configuration Debug for project DisplayImage ****
make all
Building file: ../src/DisplayImage.cpp
Invoking: GCC C++ Compiler
g++ -std=c++0x -I/usr/local/include -I/usr/local/include/opencv4 -I/usr/local/include/opencv4/opencv2 -O0 -g3 -Wall -c -fmessage-length=0 -MMD -MP -MF"src/DisplayImage.d" -MT"src/DisplayImage.o" -o "src/DisplayImage.o" "../src/DisplayImage.cpp"
Finished building: ../src/DisplayImage.cpp
Building target: DisplayImage
Invoking: GCC C++ Linker
g++ -L/usr/local/lib -o "DisplayImage" ./src/DisplayImage.o -lopencv_core -lX11 -lopencv_video -lopencv_ml -lopencv_imgproc -lopencv_img_hash -lopencv_flann -lopencv_features2d -lopencv_calib3d -lopencv_dnn -lopencv_dnn_objdetect -lopencv_cvv -lopencv_text -lopencv_datasets -lopencv_aruco -lopencv_bgsegm -lopencv_shape -lopencv_imgcodecs -lopencv_videoio -lopencv_highgui -lopencv_bioinspired
Finished building target: DisplayImage
13:59:14 Build Finished (took 835ms)
the height of the screen in pixels: 1080
the width of the screen in pixels: 1920
the black pixel value for the specified screen: 0
the white pixel value for the specified screen: 16777215
the default screen number referenced by the XOpenDisplay() function: 0
8. Screen
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
struct _XDisplay *display;/* back pointer to display structure */
Window root; /* Root window id. */
int width, height; /* width and height of screen */
int mwidth, mheight; /* width and height of in millimeters */
int ndepths; /* number of depths possible */
Depth *depths; /* list of allowable depths on the screen */
int root_depth; /* bits per pixel */
Visual *root_visual; /* root visual */
GC default_gc; /* GC for the root root visual */
Colormap cmap; /* default color map */
unsigned long white_pixel;
unsigned long black_pixel; /* White and Black pixel values */
int max_maps, min_maps; /* max and min color maps */
int backing_store; /* Never, WhenMapped, Always */
Bool save_unders;
long root_input_mask; /* initial root input mask */
} Screen;
References
https://tronche.com/gui/x/xlib/
https://linux.die.net/man/3/xopendisplay
http://xopendisplay.hilltopia.ca/index.html
https://www.x.org/wiki/guide/
https://tronche.com/gui/x/xlib/display/display-macros.html
https://tronche.com/gui/x/xlib/display/image-format-macros.html
