nigig-org/REVIEWS/PDF_DRAWCALL_STRATEGY_ANALYSIS.md

Does the PDF viewport have a minimal-drawcall strategy?

Short answer: no — and unlike CAD, the question is currently moot, because the renderer that would issue those draw calls is never called by the widget. The page content is not drawn at all.

That is the finding. Everything else below is secondary to it.

This note answers the same question asked of the CAD codebase in REVIEWS/CAD_DRAWCALL_STRATEGY_ANALYSIS.md, prompted by a datagrid brief asking for "virtual viewport on both axes" and "an optimal minimal drawcall strategy". Those are two distinct techniques. PDF has a partial version of the first and none of the second.

Read at commit 06a3de6. Sources: pdf-makepad/src/renderer.rs (710 lines), page_view.rs (585), pdf-graphics/src/cache.rs, and Makepad draw_vector.rs / draw_text.rs at the pinned rev ecf5a572ab62a1c1598909971f602f99083671cc.

Makepad's batching model was read from source, not inferred. The CAD note records getting exactly this wrong (§0.1 there), so the two new_draw_call sites in draw_vector.rs were checked by grep before any number below was computed.

0. The finding that precedes the others

PdfRenderer is exported from lib.rs and referenced by nothing in the widget's draw path:

$ grep -rn "PdfRenderer" crates/apps/pdf/ --include=*.rs
pdf-makepad/src/lib.rs:15:pub use renderer::PdfRenderer;

PdfPageWidget::draw_walk draws a background, then either a placeholder or draw_affordances — link underlines and form fields. It never constructs a PdfRenderer and never replays a RenderCommand. The 710 lines of renderer are reachable only from outside the crate.

So the honest statement of today's cost is: the page content costs zero draw calls because it is not drawn. Every number in §2 is a projection of what will happen the moment the renderer is wired in — which is precisely when a drawcall strategy stops being theoretical.

This also explains why ClipRect carries #[allow(dead_code)] // retained for the scissor-rect work in Phase 7: clipping is modelled but unused, because nothing renders.

1. Batching: Makepad provides it, the PDF renderer uses neither mechanism

Two batching mechanisms exist at the pinned rev, and the renderer opts out of both.

1.1 DrawVector — one draw call per end()

In draw/src/shader/draw_vector.rs, cx.new_draw_call(...) appears twice, both inside end(). begin() only clears acc_verts/acc_indices. stroke() and fill() tessellate into the accumulator and issue no draw call. So an arbitrary number of fills and strokes cost one draw call, provided nothing calls end() between them.

renderer.rs calls end() from finish_path(), and finish_path() runs on Save, Restore, PushClip, PopClip, ClipEvenOdd, ClipWinding — plus once at the end of render().

Save/Restore are q/Q. In real PDFs they are extremely frequent and they are graphics-state operations, not clip operations. Flushing the vector batch on q/Q is the defect: colour, stroke width and the CTM are all baked into vertices on the CPU by to_screen_with_ctm before tessellation, so a state change needs no draw-call boundary. Only a clip change genuinely does, because clipping is a GPU scissor/stencil concern.

1.2 DrawText — an explicit instance-batch API, unused

draw_text.rs exposes begin_many_instances / end_many_instances, and draw_rasterized_glyphs_abs documents the cost of not using them:

An already-open batch ran update_draw_vars when it began; running it again per call dominates CPU when thousands of glyphs share a batch.

A bare draw_abs opens and closes its own instance batch. renderer.rs contains no reference to many_instances or begin_deferred_slug_flush, so every text run is its own batch. It also alternates between three separate DrawText objects (draw_text, draw_text_bold, draw_text_code), and switching draw objects breaks a batch even when the API is used — TextFlow hits this, which is why begin_deferred_slug_flush exists.

2. Measured: replaying the corpus through the renderer's own state machine

pdf_drawcall_census.rs (kept out of tree; see §6) replays the exact finish_path rules above over every parseable page in crates/apps/pdf/tests/corpus, counting what the renderer would issue.

165 pages, 15,185 render commands.

	count
DrawVector::end()	2,578
DrawText::draw_abs()	1,331
DrawImage::draw_abs()	2
total draw calls	3,911 (23.7 / page)

What forced the vector breaks:

cause	count
Save	1,230
Restore	1,230
clip ops	2
fill/stroke paint ops	2,457

2,460 of the 2,578 vector draw calls are caused by q/Q. Two are caused by clipping. That is the whole finding in one line: the renderer flushes on the operation that does not need a flush, and the operation that does need one barely occurs.

Counterfactual — flush only when a clip actually changes, and coalesce contiguous text runs:

	count
DrawVector::end()	166 (≈ one per page)
DrawText batches	1,318
total	1,486 (9.0 / page)
reduction	2.6×

Two honest caveats on that 2.6×:

• The vector side improves 15.5× (2,578 → 166). The blended figure is dragged down by text, which dominates once vectors are fixed.
• The text figure is barely moved by contiguity alone (1,331 → 1,318) because this corpus interleaves text with vector paints. Text needs the many_instances API, not run-merging. Fixing vectors alone gets 3,911 → 1,499; the text work is a separate, larger job.

3. Virtual viewport: partially present, and better than CAD's

This is where PDF is genuinely ahead of CAD.

Present. pdf-graphics/src/cache.rs is a real LRU page cache with a byte budget rather than an entry count — the docstring gives the right reason ("one image-heavy page can cost more than fifty text pages"). It carries generation tagging so a page from an abandoned document is never shown. phase7_exit_criterion.rs asserts the behaviours by name: opening_a_large_document_does_not_render_every_page, scrolling_evicts_pages_that_left_the_viewport, a_page_from_an_abandoned_document_is_never_shown. That is a virtual viewport on the page axis, tested.

Absent. There is no culling within a page:

• draw_affordances loops every annotation on the page, filtering only by page index and visibility flags — never against the viewport rect, which it already holds as self.interaction.viewport.
• PdfRenderer::render walks the whole command list. Nothing skips a command whose geometry lies outside the visible rect. A grep for cull/offscreen/intersect in renderer.rs returns nothing.

So: virtual on the page axis, not on the intra-page axes. For a zoomed-in A0 drawing or a page with thousands of annotations, everything is submitted.

4. Do the datagrid techniques transfer?

Yes — with one that transfers better than it does for a grid, and one that transfers worse.

Technique	Transfers?	Notes
Minimal draw calls / batching	Yes, directly.	Strongest fit. A PDF page is a flat command list over one coordinate space; that is exactly what DrawVector's accumulator wants. Requires only removing flushes, not adding structure.
Virtual viewport, page axis	Already done.	cache.rs, with tests.
Virtual viewport, intra-page	Yes, but harder than a grid.	A grid computes visible rows by division: first = scroll / row_height. A PDF command list has no such index — the CTM is stateful, so you cannot know a command's screen rect without interpreting everything before it. Needs a precomputed per-command bbox built once at record time and cached alongside the commands.
Cell-hosted child widgets	Partially — as annotations.	Form fields and links are already the analogue. render_fields is the equivalent of a cell renderer, and it is where intra-page culling should land first: it is a flat list with known rects, so it is the easy half.
Proper clipping	Modelled, unimplemented.	ClipRect is dead_code; apply_clip only calls finish_path() and sets no scissor rect. Nested /BBox clips from Phase 7's render_form are therefore not honoured on the GPU path.

The important asymmetry: a datagrid's virtual viewport is cheap because cell geometry is derivable. A PDF's is expensive because geometry is accumulated. The bbox index is the price of entry, and it should be built during recording — RecordingDevice already tracks the CTM, so it is the one place that can compute a screen rect per command without a second interpretation pass.

5. What is not measured

Stated plainly, because §2 is a static replay and not a profile.

• No GPU profiling. No frame times, no counters from a live app. The ui.rs suite that would host such a benchmark is #[ignore]d on the missing Makepad headless backend, unchanged since Phase 1.
• Draw calls are a proxy, not a cost. 3,911 draw calls spread over 165 pages is ~24 per visible page, which is not alarming on a desktop GPU. The argument for fixing it is that the count scales with document complexity, not viewport size — a dense vector page multiplies q/Q without bound.
• The census counts what the renderer would do. Since the renderer is unwired (§0), these are projections. They will become real on the commit that wires it in, which is the right moment to add the guard.
• CPU tessellation cost is not measured, only draw-call boundaries. Batching removes submission overhead; it does not remove tessellation.

6. Suggested order

Cheapest first, each independently testable. No code was changed for this note.

1. Stop flushing on q/Q. Remove finish_path() from Save and Restore; keep it on the clip commands. Projected 2,578 → 166 vector draw calls. Guard with a test asserting the count for a fixture page, in the spirit of CAD's param_hash_is_not_a_shape_key... pin.
2. Cull annotations against the viewport rect in draw_affordances. The rect is already in hand; this is a few lines and is the flat, easy half of intra-page virtualisation.
3. Wire PdfRenderer into draw_walk so page content is actually drawn — with 1 and 2 already in place, so the strategy lands with the feature rather than after it.
4. Batch text via begin_many_instances, and collapse the three DrawText objects to one where the style permits, or use begin_deferred_slug_flush where it does not.
5. Implement clipping properly — give apply_clip a real scissor rect and drop the dead_code allow.
6. Per-command bbox index at record time, then cull the command list. Only worth doing after 1–5, and only if profiling justifies it.

Step 1 is the whole of the drawcall answer. Steps 2 and 6 are the whole of the virtual-viewport answer.

7. Cross-reference with CAD

	CAD	PDF
Vector batching used correctly	yes, in the 2D path	no — flushes on q/Q
Draw call per item	yes, in 3D (one per part)	no — but 2,460 flushes from state ops
Viewport culling	none	page-level yes (tested); intra-page none
Culling data structure exists	yes, benchmarked, unused on the hot path	page bboxes yes; per-command no
Renderer actually wired up	yes	no

The two codebases fail the same question in opposite directions. CAD renders everything and batches some of it. PDF batches nothing and renders none of it.