Stroking

Where filling a path simply requires details of the fill to be used, stroking a path requires far more information; varying the thickness of the line, or the dash pattern, or linecaps/joins used can can radically alter its appearance. The details of these stroke attributes are passed in a fz_stroke_state structure.

Stroke states are created and managed with reference counting using the functions described below, but unlike other structures, the definition of the structure itself is public. Callers are expected to alter the different fields in the structure themselves. The sole exception to this is the refs field, that should only be altered using the usual fz_keep_stroke_state and fz_drop_stroke_state mechanisms.

$\begin{lstlisting} typedef struct fz_stroke_state_s fz_stroke_state; \par typede... ...mit; float dash_phase; int dash_len; float dash_list[32]; }; \end{lstlisting}$

It is hoped that the meaning of the individual fields within a fz_stroke_state structure are self evident to anyone working in this field. If you are unfamiliar with any of the concepts here, see “The PDF Reference Manual” or “The Postscript Language Reference Manual” for more details.

Most simply a reference to a stroke state structure can be obtained by calling fz_new_stroke_state:

$\begin{lstlisting} /* fz_new_stroke_state: Create a new (empty) stroke state s... ...cate. */ fz_stroke_state *fz_new_stroke_state(fz_context *ctx); \end{lstlisting}$

For stroke states that include dash information, call:

$\begin{lstlisting} /* fz_new_stroke_state_with_dash_len: Create a new (empty) ... ...e *fz_new_stroke_state_with_dash_len(fz_context *ctx, int len); \end{lstlisting}$

Once obtained, references can be kept or dropped in the usual fashion:

$\begin{lstlisting} /* fz_keep_stroke_state: Take an additional reference to a ... ...p_stroke_state(fz_context *ctx, const fz_stroke_state *stroke); \end{lstlisting}$

Once more than one reference is held to a stroke state, it should be considered `frozen' or `immutable' as other reference holders may be confused by changes to it. Accordingly, we provide functions to ensure that we are holding a reference to an `unshared' stroke state:

$\begin{lstlisting} /* fz_unshare_stroke_state: Given a reference to a (possibl... ...th_dash_len(fz_context *ctx, fz_stroke_state *shared, int len); \end{lstlisting}$

Finally, we have a simple function to clone a stroke state and return a new reference to it:

$\begin{lstlisting} /* fz_clone_stroke_state: Create an identical stroke_state ... ...z_clone_stroke_state(fz_context *ctx, fz_stroke_state *stroke); \end{lstlisting}$