From 4dd1eac7c46f7be257ce10cb2ce6b79939650938 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 28 May 2022 23:11:51 -0400 Subject: Update documentation --- README.md | 62 ++++++++++++++---------------------------------------- doc/c/view.rst | 11 +++++----- doc/deployment.rst | 15 +++++++------ doc/summary.rst | 16 ++++++-------- examples/README.md | 31 +++++++++++++++++++++++++++ 5 files changed, 69 insertions(+), 66 deletions(-) create mode 100644 examples/README.md diff --git a/README.md b/README.md index f089ed7..aae05eb 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ Pugl ==== -Pugl (PlUgin Graphics Library) is a minimal portable API for GUIs which is -suitable for use in plugins. It works on X11, MacOS, and Windows, and -includes optional support for drawing with Vulkan, OpenGL, and Cairo. +Pugl (PlUgin Graphics Library) is a minimal portability layer for GUIs which is +suitable for use in plugins. It works on X11, MacOS, and Windows, and includes +optional support for drawing with Vulkan, OpenGL, and Cairo. -Pugl is vaguely similar to libraries like GLUT and GLFW, but with some -distinguishing features: +Pugl is vaguely similar to libraries like GLUT and GLFW, but has different +goals and priorities: * Minimal in scope, providing only a thin interface to isolate platform-specific details from applications. @@ -16,18 +16,18 @@ distinguishing features: * Support for embedding in native windows, for example as a plugin or component within a larger application that is not based on Pugl. - * Simple and consistent event-based API that makes dispatching in application - or toolkit code easy with minimal boilerplate. + * Explicit context and no static data, so that several instances can be used + within a single program at once. - * Suitable not only for continuously rendering applications like games, but - also event-driven applications that only draw when necessary. + * Consistent event-based API that makes dispatching in application or toolkit + code easy with minimal boilerplate. - * Explicit context and no static data whatsoever, so that several instances - can be used within a single program at once. + * Suitable for both continuously rendering applications like games, and + event-driven applications that only draw when necessary. - * Small, liberally licensed Free Software implementation that is suitable for - vendoring and/or static linking. Pugl can be installed as a library, or - used by simply copying the implementation into a project. + * Small, liberally licensed implementation that is suitable for vendoring + and/or static linking. Pugl can be installed as a library, or used by + simply copying the implementation into a project. Stability --------- @@ -66,37 +66,7 @@ all the tests at once via ninja: cd build ninja test -The `examples` directory contains several programs that serve as both manual -tests and demonstrations: - - * `pugl_embed_demo` shows a view embedded in another, and also tests - requesting attention (which happens after 5 seconds), keyboard focus - (switched by pressing tab), view moving (with the arrow keys), and view - resizing (with the arrow keys while shift is held). This program uses only - very old OpenGL and should work on any system. - - * `pugl_window_demo` demonstrates multiple top-level windows. - - * `pugl_shader_demo` demonstrates using more modern OpenGL (version 3 or 4) - where dynamic loading and shaders are required. It can also be used to test - performance by passing the number of rectangles to draw on the command line. - - * `pugl_cairo_demo` demonstrates using Cairo on top of the native windowing - system (without OpenGL), and partial redrawing. - - * `pugl_print_events` is a utility that prints all received events to the - console in a human readable format. - - * `pugl_cpp_demo` is a simple cube demo that uses the C++ API. - - * `pugl_vulkan_demo` is a simple example of using Vulkan in C that simply - clears the window. - - * `pugl_vulkan_cpp_demo` is a more advanced Vulkan demo in C++ that draws many - animated rectangles like `pugl_shader_demo`. - -All example programs support several command line options to control various -behaviours, see the output of `--help` for details. Please file an issue if -any of these programs do not work as expected on your system. +The [examples](examples) directory contains several demonstration programs that +can be used for manual testing. -- David Robillard diff --git a/doc/c/view.rst b/doc/c/view.rst index 12f146d..016c4e3 100644 --- a/doc/c/view.rst +++ b/doc/c/view.rst @@ -28,13 +28,14 @@ For example: .. code-block:: c - const double defaultWidth = 1920.0; - const double defaultHeight = 1080.0; + const PuglSpan defaultWidth = 1920; + const PuglSpan defaultHeight = 1080; puglSetWindowTitle(view, "My Window"); - puglSetDefaultSize(view, defaultWidth, defaultHeight); - puglSetMinSize(view, defaultWidth / 4.0, defaultHeight / 4.0); - puglSetAspectRatio(view, 1, 1, 16, 9); + puglSetSizeHint(view, PUGL_DEFAULT_SIZE, 1920, 1080); + puglSetSizeHint(view, PUGL_MIN_SIZE, 640, 480); + puglSetSizeHint(view, PUGL_MIN_ASPECT, 1, 1); + puglSetSizeHint(view, PUGL_MAX_ASPECT, 16, 9); There are also several :enum:`hints ` for basic attributes that can be set: diff --git a/doc/deployment.rst b/doc/deployment.rst index 4afc51a..1e98e62 100644 --- a/doc/deployment.rst +++ b/doc/deployment.rst @@ -9,15 +9,18 @@ Building Against Pugl When Pugl is installed, pkg-config_ packages are provided that link with the core platform library and desired backend: -- ``pugl-cairo-0`` -- ``pugl-gl-0`` -- ``pugl-vulkan-0`` +.. code-block:: sh + + pkg-config --cflags --libs pugl-0 + pkg-config --cflags --libs pugl-cairo-0 + pkg-config --cflags --libs pugl-gl-0 + pkg-config --cflags --libs pugl-vulkan-0 Depending on one of these packages should be all that is necessary to use Pugl, but details on the individual libraries that are installed are available in the README. -If you are instead including the source directly in your project, -the structure is quite simple and hopefully obvious. -It is only necessary to copy the platform and backend implementations that you need. +If you are instead building directly from source, +all of the implementation files are in the ``src`` directory. +It is only necessary to build the platform and backend implementations that you need. .. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/ diff --git a/doc/summary.rst b/doc/summary.rst index f05515f..e9cdc62 100644 --- a/doc/summary.rst +++ b/doc/summary.rst @@ -1,21 +1,19 @@ -Pugl is an API for writing portable and embeddable GUIs. +Pugl is a library for writing portable and embeddable GUIs. Pugl is not a toolkit or framework, but a minimal portability layer that sets up a drawing context and delivers events. -Compared to other libraries, Pugl is particularly suitable for use in plugins or other loadable modules. -There is no implicit context or static data in the library, +It has no implicit context or mutable static data, so it may be statically linked and used multiple times in the same process. -Pugl has a modular design that separates the core library from graphics backends. -The core library is graphics agnostic, -it implements platform support and depends only on standard system libraries. +Pugl has a modular design with a core library and separate graphics backends. +The core library implements platform support and depends only on standard system libraries. MacOS, Windows, and X11 are currently supported as platforms. -Graphics backends are separate so that applications only depend on the API that they use. +Graphics backends are built as separate libraries, +so applications can depend only on the APIs that they use. Pugl includes graphics backends for Cairo_, OpenGL_, and Vulkan_. -It is also possible to use some other graphics API by implementing a custom backend, -or simply accessing the native platform handle for a window. +Other graphics APIs can be used by implementing a custom backend. .. _Cairo: https://www.cairographics.org/ .. _OpenGL: https://www.opengl.org/ diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..20538c3 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,31 @@ +These programs serve as demonstrations, and as utilities for manual testing. + + * `pugl_embed_demo` shows a view embedded in another, and also tests + requesting attention (which happens after 5 seconds), keyboard focus + (switched by pressing tab), view moving (with the arrow keys), and view + resizing (with the arrow keys while shift is held). This program uses only + very old OpenGL and should work on any system. + + * `pugl_window_demo` demonstrates multiple top-level windows. + + * `pugl_shader_demo` demonstrates using more modern OpenGL (version 3 or 4) + where dynamic loading and shaders are required. It can also be used to test + performance by passing the number of rectangles to draw on the command line. + + * `pugl_cairo_demo` demonstrates using Cairo on top of the native windowing + system (without OpenGL), and partial redrawing. + + * `pugl_print_events` is a utility that prints all received events to the + console in a human readable format. + + * `pugl_cpp_demo` is a simple cube demo that uses the C++ API. + + * `pugl_vulkan_demo` is a simple example of using Vulkan in C that simply + clears the window. + + * `pugl_vulkan_cpp_demo` is a more advanced Vulkan demo in C++ that draws many + animated rectangles like `pugl_shader_demo`. + +All example programs support several command line options to control various +behaviours, see the output of `--help` for details. Please file an issue if +any of these programs do not work as expected on your system. -- cgit v1.2.1