8.2.10 Shape interface

The shape interface is an interface for leaf nodes which export their appearance as (a set of) polygons. It does not have any interesting public methods.

Every object implementing the shape interface must also implement the object interface and the node interface. No object implementing the shape interface is allowed to implement any of the container or mask interfaces.

Polygonize method

     void * vcl_shape_polygonize (void * obj, void * it, double delta,
                                  const struct geom_transform *t,
                                  const struct geom_rectangle *bbox,
                                  u8 ** buff, uns * buff_len, uns *closed,
                                  uns *points, uns hints)

This method is requested for expressing a part of the area occupied by obj by one polygon (or polyline). This function is supposed to be called in an iterative way – in every call one polygon/polyline is returned. In first call, the it argument should be NULL, and next calls should have it set to the return value of the previous call. If the return value is NULL, then there should be no other calls. All iterations must be done (there is no way to escape during the cycle).

The delta argument means the precision of the approximation. The t argument is the required transformation from the obj's coordinate system to pixel coordinate system (the primary transformation matrix). The bbox argument is the bounding box of caller's area of interest – anything out of it is not required to be approximated within the given precision, but must have a correct connection to the next point inside the bounding box. Any polygons/polylines which are entirely outside bbox can be skipped. bbox is in obj's coordinates.

The buff and buff_len arguments are for point buffer – if the buffer is small (or NULL), then the callee is responsible for reallocating it using xmalloc or xrealloc and update the value in *buff_len, which is the buffer size in bytes. The caller can give some hints using the hints argument, but the callee can ignore them. The hints are the following flags: VCL_SHAPE_CLOSED_ONLY – the callee can skip polylines, VCL_SHAPE_OPEN_ONLY – the callee can skip polygons.

Polygons/polylines are returned using an array of struct geom_rectangle stored in the buffer, the number of points is returned in *points, *closed indicates whether the returned object is a polygon (=1) or a polyline (=0).