utils: Add a dump_framebuffer() method
[renesas/kmsxx.git] / README.md
1 [![Build Status](https://travis-ci.org/tomba/kmsxx.svg?branch=master)](https://travis-ci.org/tomba/kmsxx)
2
3 # kms++ - C++ library for kernel mode setting
4
5 kms++ is a C++17 library for kernel mode setting.
6
7 Also included are some simple utilities for KMS and python bindings for kms++.
8
9 ## Utilities
10
11 - kmstest - set modes and planes and show test pattern on crtcs/planes, and test page flips
12 - kmsprint - print information about DRM objects
13 - kmsview - view raw images
14 - kmscube - rotating 3D cube on crtcs/planes
15 - kmscapture - show captured frames from a camera on screen
16
17 ## Dependencies:
18
19 - libdrm
20 - Python 3.x (for python bindings)
21
22 ## Build instructions:
23
24 To build the Python bindings you need to set up the git-submodule for pybind11:
25
26 ```
27 git submodule update --init
28 ```
29
30 And to compile:
31
32 ```
33 meson build
34 ninja -C build
35 ```
36
37 ## Cross compiling instructions:
38
39 ```
40 meson build --cross-file=<path-to-meson-cross-file>
41 ninja -C build
42 ```
43
44 Here is my cross file for arm32 (where ${BROOT} is path to my buildroot output dir):
45
46 ```
47 [binaries]
48 c = ['ccache', '${BROOT}/host/bin/arm-buildroot-linux-gnueabihf-gcc']
49 cpp = ['ccache', '${BROOT}/host/bin/arm-buildroot-linux-gnueabihf-g++']
50 ar = '${BROOT}/host/bin/arm-buildroot-linux-gnueabihf-ar'
51 strip = '${BROOT}/host/bin/arm-buildroot-linux-gnueabihf-strip'
52 pkgconfig = '${BROOT}/host/bin/pkg-config'
53
54 [host_machine]
55 system = 'linux'
56 cpu_family = 'arm'
57 cpu = 'arm'
58 endian = 'little'
59 ```
60
61 ## Build options
62
63 You can use meson options to configure the build. E.g.
64
65 ```
66 meson build -Dbuildtype=debug -Dkmscube=true
67 ```
68
69 Use `meson configure build` to see all the configuration options and their current values.
70
71 kms++ specific build options are:
72
73 Option name      | Values                  | Default         | Notes
74 ---------------- | -------------           | --------------- | --------
75 pykms            | true, false             | true            | Python bindings
76 kmscube          | true, false             | false           | GLES kmscube
77 omap             | enabled, disabled, auto | auto            | libdrm-omap support
78
79 ## Env variables
80
81 You can use the following runtime environmental variables to control the behavior of kms++.
82
83 Variable                          | Description
84 --------------------------------- | -------------
85 KMSXX_DISABLE_UNIVERSAL_PLANES    | Set to disable the use of universal planes
86 KMSXX_DISABLE_ATOMIC              | Set to disable the use of atomic modesetting
87 KMSXX_DEVICE                      | Path to the card device node to use
88 KMSXX_DRIVER                      | Name of the driver to use. The format is either "drvname" or "drvname:idx"
89
90 ## Python notes
91
92 You can run the python code directly from the build dir by defining PYTHONPATH env variable. For example:
93
94 ```
95 PYTHONPATH=build/py py/tests/hpd.py
96 ```