PDFCube

PDFCube is a PDF presentation viewer with animated transitions, automatic slide timing, and keyboard-controlled zoom. It brings cube rotations, page flips, shattering glass, and smooth fades to slide decks from LaTeX Beamer and office suites.

showcase.mp4

Autogenerated showcase · 30 fps · source 865ad7da6f54770e53925a5f4c5b1f0867819a37.

Explore the transitions and their design, try the example PDFs, or read about the LaTeX/Beamer showcase.

Download the released showcase PDF from the latest GitHub release, listed as pdfcube-VERSION-showcase.pdf. Open it in PDFCube to try all the transitions. It is also included in Debian packages and AppImages.

Requirements

PDFCube uses C++20, GTK 4 GtkGLArea, shader-based OpenGL/OpenGL ES 3, libepoxy, Poppler GLib, Cairo, Boost Program Options, and Meson.

PDFCube requires GTK 4.12 or newer, Poppler GLib 22.0 or newer, and an OpenGL or OpenGL ES 3.0-capable driver. On Debian 13 or Ubuntu 24.04, install the build dependencies with:

sudo apt install g++ meson ninja-build pkg-config \
  libgtk-4-dev libepoxy-dev libpoppler-glib-dev libcairo2-dev \
  libboost-program-options-dev

The fast test suite additionally uses Python 3, Pillow, EGL development headers, and Mesa's software OpenGL driver. Install them with:

sudo apt install python3 python3-pil dbus-daemon libegl-dev libgl1-mesa-dri fonts-dejavu-core

Frame tests render explicit progress values in one headless context per case; synthetic progress makes each capture independent of playback duration. Every test has a 500 ms timing SLO, checked before pushing, including cold graphics setup. Timing misses are reported separately from functional failures. See the test contract. The optional review gallery additionally requires Xvfb, Xauth, and ffmpeg.

On macOS with Homebrew:

brew install meson ninja pkg-config gtk4 libepoxy poppler boost

On Windows, use an MSYS2 UCRT64 shell and install:

pacman -S --needed mingw-w64-ucrt-x86_64-{toolchain,meson,ninja,python,gtk4,libepoxy,poppler,boost}

The renderer selects GLSL 1.30 or GLSL ES 3.00 to match the context supplied by GTK. Linux is tested on X11 and Wayland; CI also compiles and exercises the command-line interface on Windows and macOS. Actual GPU/driver combinations are tracked in COMPATIBILITY.md with their validation status.

Build and install

meson setup build --buildtype=release
meson compile -C build
meson test -C build --print-errorlogs
sudo meson install -C build

Build the Beamer showcase explicitly with meson compile -C build doc. This documentation target requires TeX Live with Beamer and PGF/TikZ; see the showcase build instructions. The doc target builds documentation separately from the default application target.

Run directly from a local build:

./build/src/pdfcube presentation.pdf

See INSTALL for prefix, staging, and uninstall instructions.

Usage

Run pdfcube --help for the complete command-line interface. The established options remain available:

• --bgcolor r:g:b sets the background color.
• --top-color r:g:b sets the cube cap and Push side color.
• --demo enables automatic slide advancement.
• --experimental enables optional animation details, currently thin glass shard edges in Dissolve. It is off by default.
• --program n:x:... programs durations and transition types, including cube (c), plain (p), and the documented PDF effects.
• --performance-log timings.csv buffers animation frame timings and writes them on exit, keeping file I/O outside active animation.
• --no-fullscreen starts in a window.

When no PDF is supplied, PDFCube opens a GTK file chooser. Options can also be stored in ~/.pdfcuberc; command-line values take precedence.

Common controls include Space or Page Down to advance, c/a for forward and backward cube transitions, arrow keys for plain navigation, h/j/k/ l/z for zoom regions, g to reset zoom, f for fullscreen, and Escape or Ctrl-Q to quit. Number keys 1–9 jump to pages 1, 6, 11, and so on; the separate Ctrl-1–Ctrl-9 bindings jump to the corresponding cube section. Zoom keys h, j, k, and l focus the upper-left, upper-right, lower-left, and lower-right regions; z focuses slightly below the page center. They retain the original framing and 750 ms camera motion. Any zoom key while zoomed in (or g) returns to the full page. See man pdfcube for the full list.

Frame pacing

PDFCube follows GTK's compositor-synchronized frame clock. Full-resolution previous and next pages are rendered in the background and uploaded to the GPU while the current slide is idle. If a page is not ready when navigation is requested, the transition remains at its exact first frame until preparation finishes. The animation clock starts once both full-resolution textures are ready.

Use --performance-log timings.csv with a representative presentation. The CSV records displayed-frame intervals, CPU submission time, and whether a frame was the stationary preparation frame. At 60 Hz, animation-frame intervals should remain close to 16,667 microseconds; at 120 Hz, close to 8,333. CPU submission measures CPU work; GPU completion is asynchronous. Interval spikes help identify compositor or rendering stalls. Slides retain full texture resolution throughout the animation.

Tests

meson test -C build --print-errorlogs

The suite checks the public command-line contract and produces deterministic headless rendering snapshots in surfaceless EGL contexts, plus one GTK integration snapshot under Xvfb. It covers page rendering, cube and plain programs, configured colors, and command-line-over-config precedence. --snapshot and --snapshot-progress are private regression-test hooks.

See the documentation and usability roadmap for planned improvements.

Release and packaging

Meson can produce a tested source archive with:

meson dist -C build --formats gztar

Every successful push to master creates the next patch release automatically. MIN_VERSION is the release floor: raise its major or minor component manually when needed. The workflow creates the corresponding tag and a GitHub Release containing the source archive, a Debian package built on the latest Ubuntu LTS runner, an x86-64 AppImage, a macOS DMG, a Windows x86-64 MSI, the Beamer showcase PDF, and SHA-256 checksums. The DMG and MSI contain their GTK and supporting runtime libraries and are smoke-tested after packaging.

Debian packaging is maintained in debian/; native package assembly lives in packaging/macos/ and packaging/windows/. Maintainers should follow RELEASING.md before creating a release tag.

License

PDFCube is licensed under the GNU General Public License, version 2 or later. See LICENSE.

PDFCube was created by Mirko Maischberger, with contributions from Karol Sokolowski and others listed in the Git history.