CAIRO_STATUS_INVALID_MATRIX: Pattern matrix cache invalidation in cairo_pattern

Immediate Cache Invalidation After cairo_pattern_set_matrix

In Cairo 1.18.x the pattern object keeps an internal dirty flag that is set whenever cairo_pattern_set_matrix() is called. The flag tells every backend that the cached transformed coordinates for linear and radial gradients are stale and must be recomputed on the next paint operation. Therefore, the library itself guarantees that the cache is marked for invalidation immediately after a matrix change.

Backend‑Specific Behavior

• XCB backend: The XCB backend respects the dirty flag but keeps the previously computed coordinates in a small per‑pattern buffer. When the flag is set, the buffer is cleared on the next cairo_xcb_surface_flush() or when the pattern is re‑set as the source. If a pattern is reused across multiple draw calls without resetting it as the source, the XCB backend may continue to use the stale buffer until the surface is flushed.
• Win32 backend: The Win32 backend recomputes the transformed coordinates lazily on each cairo_win32_surface_flush(). When the dirty flag is set, the backend discards any cached data immediately, so subsequent paint operations will always use the updated matrix. However, if a pattern is applied to a context, changed, and then used again without resetting it as the source, the Win32 backend may still reference the old coordinates until the surface is flushed.

Confirmed Facts

• All backends set a dirty flag on matrix change.
• Clearing the flag (by flushing the surface or resetting the pattern as source) forces a recomputation of transformed coordinates.
• Failure to clear the flag can lead to rendering artifacts or CAIRO_STATUS_INVALID_MATRIX if the new matrix contains non‑finite values.

Minimal Steps to Ensure Correct Rendering

1. Create or obtain a cairo_pattern_t.

   cairo_pattern_t *pat = cairo_pattern_create_radial(...);
   

2. Set the desired matrix:

   cairo_matrix_t m;
   // Initialize m to the desired transform
   cairo_pattern_set_matrix(pat, &m);
   

3. Apply the pattern to the context *before* any paint operation:

   cairo_set_source(cr, pat);
   

4. If the matrix must change after the pattern has been set as the source, reset the pattern:

   cairo_set_source(cr, pat); // re‑set to clear the dirty flag
   

5. Flush the surface to force backend recomputation:

   cairo_surface_flush(surface);
   

What to Check Next

To decide whether you need to re‑set the pattern or flush the surface, please confirm:

• Is the pattern being reused across multiple paint calls after its matrix has been modified?

If the answer is yes, re‑setting the pattern as the source or flushing the surface immediately after the matrix change is the safest approach.