Skip to content

MLP213: calibrated large Cairo Surface workload

qual reports MLP213 when a Surface with a literal resolution of at least 1,024 faces is a certain direct animation target under an active Cairo profile. Cairo represents the surface as a family of VMobject faces and repeatedly sorts, projects, shades, strokes, and rasterizes them while the surface moves; OpenGL has a mesh path suited to this workload.

  • Default severity: info
  • Minimum confidence: medium
  • Implementation phase: 3
  • Profiles: Cairo only
  • Fix: none

The CAIRO_SURFACE_FACE_GATE boundary is 32 × 32 = 1,024 faces. It is tied to the versioned measurement in docs/research/perf-evidence.md, which records the audited source snapshot and a 1,024-face Cairo probe. The rule uses only the symbolic faces × frames dimensions: it never presents the calibration machine's milliseconds as portable timing.

An integer resolution contributes n²; a two-element literal tuple/list contributes u × v. Unknown, starred, non-positive, smaller, unplayed, or branch-only resolutions stay silent. OpenGL-only runs also stay silent.

Wrong for Cairo

class Demo(ThreeDScene):
    def construct(self):
        surface = Surface(lambda u, v: (u, v, 0), resolution=(32, 32))
        self.play(surface.animate.shift(RIGHT), run_time=3)

Use a smaller resolution when it preserves the required detail:

surface = Surface(lambda u, v: (u, v, 0), resolution=(16, 16))

For genuinely dense, moving surfaces, render with an OpenGL profile after checking that the scene's other APIs are renderer-compatible.