README
1This is not part of ZToolkit, but is used with
2ZToolkit.
3
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 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
40Distribution
41------------
42
43Pugl is designed for flexible distribution. It can be used by simply including
44the source code, or installed and linked against as a static or shared library.
45Static linking or direct inclusion is a good idea for plugins that will be
46distributed as binaries to avoid dependency problems.
47
48If you are including the code, please use a submodule so that suitable changes
49can be merged upstream to keep fragmentation to a minimum.
50
51When installed, Pugl is split into different libraries to keep dependencies
52minimal. The core implementation is separate from graphics backends:
53
54 * The core implementation for a particular platform is in one library:
55 `pugl_x11`, `pugl_mac`, or `pugl_win`. This does not depend on backends or
56 their dependencies.
57
58 * Backends for platforms are in separate libraries, which depend on the core:
59 `pugl_x11_cairo`, `pugl_x11_gl`, `pugl_mac_cairo`, and so on.
60
61Applications must link against the core and at least one backend. Normally,
62this can be achieved by simply depending on the package `pugl-gl-0` or
63`pugl-cairo-0`. Though it is possible to compile everything into a monolithic
64library, distributions should retain this separation so that GL applications
65don't depend on Cairo and its dependencies, or vice-versa.
66
67Distributions are encouraged to include static libraries if possible so that
68developers can build portable plugin binaries.
69
70Documentation
71-------------
72
73 * [API reference](https://lv2.gitlab.io/pugl/)
74
75 -- David Robillard <d@drobilla.net>
76