README.md
1Pugl
2====
3
4Pugl (PlUgin Graphics Library) is a minimal portable API for GUIs which is
5suitable for use in plugins. It works on X11, MacOS, and Windows, and
6optionally supports Vulkan, OpenGL, and Cairo graphics contexts.
7
8Pugl is vaguely similar to libraries like GLUT and GLFW, but with some
9distinguishing features:
10
11 * Minimal in scope, providing only a thin interface to isolate
12 platform-specific details from applications.
13
14 * Zero dependencies, aside from standard system libraries.
15
16 * Support for embedding in native windows, for example as a plugin or
17 component within a larger application that is not based on Pugl.
18
19 * Simple and extensible event-based API that makes dispatching in application
20 or toolkit code easy with minimal boilerplate.
21
22 * Suitable not only for continuously rendering applications like games, but
23 also event-driven applications that only draw when necessary.
24
25 * Explicit context and no static data whatsoever, so that several instances
26 can be used within a single program at once.
27
28 * Small, liberally licensed Free Software implementation that is suitable for
29 vendoring and/or static linking. Pugl can be installed as a library, or
30 used by simply copying the headers into a project.
31
32Stability
33---------
34
35Pugl is currently being developed towards a long-term stable API. For the time
36being, however, the API may break occasionally. Please report any relevant
37feedback, or file feature requests, so that we can ensure that the released API
38is stable for as long as possible.
39
40Documentation
41-------------
42
43Pugl is a C library that includes C++ bindings.
44Each API is documented separately:
45
46 * [C Documentation (single page)](https://lv2.gitlab.io/pugl/c/singlehtml/)
47 * [C Documentation (paginated)](https://lv2.gitlab.io/pugl/c/html/)
48 * [C++ Documentation (single page)](https://lv2.gitlab.io/pugl/cpp/singlehtml/)
49 * [C++ Documentation (paginated)](https://lv2.gitlab.io/pugl/cpp/html/)
50
51The documentation can also be built from the source by configuring with `--docs`.
52
53Testing
54-------
55
56There are a few unit tests included, but unfortunately manual testing is still
57required. The tests and example programs will be built if you pass the
58`--test` option when configuring:
59
60 ./waf configure --test
61
62Then, after building, the unit tests can be run:
63
64 ./waf
65 ./waf test --gui-tests
66
67The `examples` directory contains several programs that serve as both manual
68tests and demonstrations:
69
70 * `pugl_embed_demo` shows a view embedded in another, and also tests
71 requesting attention (which happens after 5 seconds), keyboard focus
72 (switched by pressing tab), view moving (with the arrow keys), and view
73 resizing (with the arrow keys while shift is held). This program uses only
74 very old OpenGL and should work on any system.
75
76 * `pugl_window_demo` demonstrates multiple top-level windows.
77
78 * `pugl_shader_demo` demonstrates using more modern OpenGL (version 3 or 4)
79 where dynamic loading and shaders are required. It can also be used to test
80 performance by passing the number of rectangles to draw on the command line.
81
82 * `pugl_cairo_demo` demonstrates using Cairo on top of the native windowing
83 system (without OpenGL), and partial redrawing.
84
85 * `pugl_print_events` is a utility that prints all received events to the
86 console in a human readable format.
87
88 * `pugl_cxx_demo` is a simple cube demo that uses the C++ API.
89
90 * `pugl_vulkan_demo` is a simple example of using Vulkan in C that simply
91 clears the window.
92
93 * `pugl_vulkan_cxx_demo` is a more advanced Vulkan demo in C++ that draws many
94 animated rectangles like `pugl_shader_demo`.
95
96All example programs support several command line options to control various
97behaviours, see the output of `--help` for details. Please file an issue if
98any of these programs do not work as expected on your system.
99
100 -- David Robillard <d@drobilla.net>
101