mirror of
https://github.com/storytold/pdfcraft.git
synced 2026-10-25 18:47:22 -06:00
36468f0ad4
* Windows: vendor egui-wgpu 0.36.2 as published (#577) The crate as released on crates.io, plus egui's LICENSE-APACHE and LICENSE-MIT from the 0.36.2 tag (the published crate leaves them out). Not used yet: the next commit patches it and adds it to [patch.crates-io]. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Windows: a window larger than the GPU's texture limit can't close PdfCraft (#577) egui-wgpu 0.36.2 configures a window's surface at the window's own size. Beyond the device's max_texture_dimension_2d, Surface::configure fails validation and wgpu's default error handler panics. eframe configures the surface before the app is created, so no app code can intercept it (emilk/egui#8361). #578 raised the device's limit to the adapter's; this removes the crash for windows larger than even that. vendor/egui-wgpu: `winit::surface_fit` shrinks both sides by one factor so neither exceeds the limit (the longer side lands exactly on it), and egui draws at that factor into the surface. On DX12, PdfCraft's Windows default, the swapchain is stretched over the window (DXGI_SCALING_STRETCH), so the window stays complete and lined up with the pointer, only softer; wgpu's GL backend copies it unscaled into a corner instead. It applies wherever a surface is sized: install, resize (start-up restore, maximise, DPI change, fullscreen) and a recreated surface, which starts again from the window's own size. Depth and MSAA textures follow. A surface logs a warning when it becomes fitted. Why only an Outlook launch hit it (read from the code, not observed): winit creates the window at CW_USEDEFAULT, so Windows places it, and a launcher that hands ShellExecute its own window gets new windows on its monitor. winit then converts the restored logical size at that monitor's scale: 3440 points became 8600 pixels on a 250% panel. eframe's clamp compares points against the largest monitor, so it let 3440 through. Tests: surface_fit with the issue's 8600 x 3423 and edge sizes (zero, u32::MAX, a zero limit, the longer side exactly on the limit); egui-wgpu resolves to vendor/egui-wgpu and the fit stays wired into the paths that size a surface. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Windows: a GPU that can't set up the window falls back to OpenGL (#519) On a 2015 Intel GPU with no D3D12 driver, wgpu picked its GL adapter over WARP and Surface::configure failed (GpuWaitTimeout). wgpu's default error handler panics, and eframe configures the root surface before the app is created, so the OpenGL retry from #530 never ran. Vendored egui-wgpu (PdfCraft patch #519): winit::catch_errors runs a closure inside wgpu error scopes (validation, out of memory, internal) and returns the error. Painter::add_surface configures each new window's surface inside it and returns a failure as WgpuError::ConfigureSurface, so eframe returns Error::Wgpu and main retries with glow. Later reconfigures are unchanged. Tests: a real device returns a wgpu validation error from catch_errors instead of panicking (red with the scopes removed), and add_surface keeps the wiring (red with it removed). Docs: vendor/README.md patch 2, docs/development.md "Renderer fallback" and PDFCRAFT_RENDERER, ROADMAP. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * vendor/egui-wgpu: drop the stray .cargo-ok marker * Tests: the GPU error-scope test skips on a machine without a GPU adapter --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Brandon Thomas <echelon@gmail.com>
66 lines
4.6 KiB
Markdown
66 lines
4.6 KiB
Markdown
# Developing PdfCraft
|
|
|
|
Working instructions for agents and contributors are in `AGENTS.md` and `CLAUDE.md`. This page
|
|
collects what the desktop app reads from its environment and where it writes its diagnostics.
|
|
|
|
## Logs
|
|
|
|
The desktop app writes its `log` records to standard error and to `logs/pdfcraft.log` in its
|
|
settings folder, next to `app.ron`: Linux and FreeBSD `~/.local/share/pdfcraft/logs/` (or
|
|
`$XDG_DATA_HOME/pdfcraft/logs/`), macOS `~/Library/Application Support/PdfCraft/logs/`, Windows
|
|
`%APPDATA%\PdfCraft\data\logs\`. In portable mode (a `portable.txt` file next to the executable, as
|
|
the Windows portable zip ships) the settings folder is `PdfCraftData\` beside the executable, and
|
|
crash recovery and new digital IDs go there too. A start from a desktop menu, Finder or the Start
|
|
menu has no terminal, so this file is what to attach to a bug report: a failed autosave, a page that
|
|
would not render, a render worker that could not start and the report of an internal error all land
|
|
there.
|
|
Each launch moves the previous log to `pdfcraft.1.log` (and that one to `pdfcraft.2.log`), so the
|
|
log of a run that crashed survives the next start. The file stops growing at 16 MiB. `--version`
|
|
writes no file.
|
|
|
|
By default PdfCraft's own crates (`pdfcraft*`) log at `info` and everything else at `warn`.
|
|
`RUST_LOG` replaces that with env_logger-style directives, for example `RUST_LOG=debug`,
|
|
`RUST_LOG=warn,pdfcraft_render=trace` or `RUST_LOG=info,wgpu_core=warn`; a directive ending in `*`
|
|
covers every target starting with it (`pdfcraft*=debug`). The logger is
|
|
`apps/pdfcraft/src/logging.rs`. It never records the control-channel token or document passwords.
|
|
|
|
## GPU surface limits
|
|
|
|
The desktop renderer enables the selected adapter's supported 2D texture extent, while keeping
|
|
egui-wgpu's other device requirements. Restored windows on mixed-DPI monitors can exceed its
|
|
default 8192-pixel extent even when the GPU supports a larger surface (#577). The enabled extent
|
|
never exceeds the adapter's capability. A window larger than even that (restored at another
|
|
monitor's scale, or stretched across monitors) gets a surface fitted within the limit and is drawn
|
|
at a correspondingly lower scale instead of panicking in `Surface::configure` (vendored egui-wgpu,
|
|
`surface_fit`; see `vendor/README.md`). On DX12, PdfCraft's Windows default, the surface is
|
|
stretched over the window: softer, but complete and lined up with the pointer. wgpu's GL backend
|
|
copies it unscaled into a corner of the window instead.
|
|
|
|
## Renderer fallback
|
|
|
|
PdfCraft draws with wgpu, and starts again with eframe's own OpenGL renderer (glow) when wgpu fails
|
|
before the app is created: no adapter, no device, or a window surface the device can't configure.
|
|
The last of these was a panic, not an error, because wgpu's default error handler panics and
|
|
eframe configures the surface before any app code runs; a 2015 Intel GPU whose driver timed out in
|
|
`Surface::configure` on wgpu's GL backend closed PdfCraft at launch (#519). Vendored egui-wgpu
|
|
configures a new window's surface inside `winit::catch_errors` and returns a validation,
|
|
out-of-memory or internal error as `WgpuError::ConfigureSurface` (see `vendor/README.md`). Still a
|
|
panic, as upstream: an error in a later reconfigure (resizing, a lost surface); a device lost
|
|
during that first configure (wgpu reports it only to a callback, so the first frame panics, after
|
|
the app has started); and a window shown at zero size, which is first configured on resize. If
|
|
OpenGL can't start either, PdfCraft exits with both errors in the log. The fallback is logged at
|
|
`error`, with the wgpu error. `PDFCRAFT_RENDERER` skips it or chooses OpenGL from the start.
|
|
|
|
## Environment variables
|
|
|
|
| Variable | Effect |
|
|
|---|---|
|
|
| `RUST_LOG` | Log levels for standard error and the log file (see [Logs](#logs)) |
|
|
| `RUST_BACKTRACE` | `1` adds a backtrace to the report of an internal error |
|
|
| `XDG_DATA_HOME` | Linux/FreeBSD: base of the settings folder (`pdfcraft/`), the log folder and crash recovery |
|
|
| `WGPU_POWER_PREF` | GPU choice; by default PdfCraft prefers the low-power (integrated) GPU |
|
|
| `WGPU_BACKEND` | Graphics backend; by default Windows uses Direct3D 12, falling back to OpenGL |
|
|
| `PDFCRAFT_RENDERER` | `gl` starts with OpenGL (glow) and never loads wgpu; `wgpu` reports a wgpu failure instead of retrying with OpenGL; unset, wgpu is retried with OpenGL when it can't start (see [Renderer fallback](#renderer-fallback)) |
|
|
| `CRAFT_FONTS_DIR` | Build time: a [craft-fonts](https://github.com/storytold/craft-fonts) checkout to embed (Japanese fonts) |
|
|
| `PDFCRAFT_SYSTEM_FONTS` | `0` stops the desktop app from using an installed font for characters its embedded fonts lack (`cargo xtask screenshots` sets it) |
|