22.7 Tiling

Many document formats allow for content to be tiled repeatedly. Frequently this is used to implement patterns for filling other graphical operations.

MuPDF implements this by allowing a group of content to be defined that is then tiled repeatedly across an area.

The content definition begins by calling fz_begin_tile_id, giving the area of the page to be filled (area), the area of a single tile (view), the x and y steps between repeats of the tile (xstep and ystep), the transformation to take all of these measurements out of pattern space to device space (ctm) and an integer id.

The purpose of id is to allow for efficient caching of rendered tiles. If id is 0, then no caching is performed. If it is non-zero, then it assumed to uniquely identify this tile. The tile can be safely placed into the Store (see chapter 7 Memory Management and The Store) and future uses of this tile can short circuit the tile definition/rendering phase.

If a tile is found in the store, then fz_begin_tile_id will return non-zero and the caller can proceed directly to the call to fz_end_tile.

Any graphical operations sent to the device will be taken as part of the tile content, until fz_end_tile is called, whereupon these graphical operations will be imposed upon the output.

For the convenience of the caller, if no id is available (and hence no caching is possible), the fz_begin_tile variant can be used instead.

The id is set by the caller - i.e. the interpreter for the document format in use. Care should be taken by the caller to make these unique.

void fz_begin_tile(fz_context *ctx, fz_device *dev, const fz_rect *area, const fz_rect *view, float xstep, float ystep, const fz_matrix *ctm); 
int fz_begin_tile_id(fz_context *ctx, fz_device *dev, const fz_rect *area, const fz_rect *view, float xstep, float ystep, const fz_matrix *ctm, int id); 
void fz_end_tile(fz_context *ctx, fz_device *dev);