PDF-path

#ifndef MUPDF_FITZ_PATH_H
#define MUPDF_FITZ_PATH_H

#include “mupdf/fitz/system.h”
#include “mupdf/fitz/context.h”
#include “mupdf/fitz/geometry.h”

/**

• Vector path buffer.

• It can be stroked and dashed, or be filled.

• It has a fill rule (nonzero or even_odd).

• When rendering, they are flattened, stroked and dashed straight

• into the Global Edge List.

  矢量路径缓冲区。
  它可以被抚摸和划线，或者被填充。
  它有一个填充规则（非零或 even_odd）。

  渲染时，它们被展平、描边和直线划线
  进入全局边缘列表。
  */

typedef struct fz_path fz_path;

typedef enum
{
FZ_LINECAP_BUTT = 0,
FZ_LINECAP_ROUND = 1,
FZ_LINECAP_SQUARE = 2,
FZ_LINECAP_TRIANGLE = 3
} fz_linecap;

typedef enum
{
FZ_LINEJOIN_MITER = 0,
FZ_LINEJOIN_ROUND = 1,
FZ_LINEJOIN_BEVEL = 2,
FZ_LINEJOIN_MITER_XPS = 3
} fz_linejoin;

typedef struct
{
int refs;
fz_linecap start_cap, dash_cap, end_cap;
fz_linejoin linejoin;
float linewidth;
float miterlimit;
float dash_phase;
int dash_len;
float dash_list[32];
} fz_stroke_state;

typedef struct
{
/* Compulsory ones */
void (*moveto)(fz_context *ctx, void *arg, float x, float y);
void (*lineto)(fz_context *ctx, void *arg, float x, float y);
void (*curveto)(fz_context *ctx, void *arg, float x1, float y1, float x2, float y2, float x3, float y3);
void (*closepath)(fz_context *ctx, void arg);
/ Optional ones */
void (*quadto)(fz_context *ctx, void *arg, float x1, float y1, float x2, float y2);
void (*curvetov)(fz_context *ctx, void *arg, float x2, float y2, float x3, float y3);
void (*curvetoy)(fz_context *ctx, void *arg, float x1, float y1, float x3, float y3);
void (*rectto)(fz_context *ctx, void *arg, float x1, float y1, float x2, float y2);
} fz_path_walker;

/**
Walk the segments of a path, calling the
appropriate callback function from a given set for each
segment of the path.

path: The path to walk.

walker: The set of callback functions to use. The first
4 callback pointers in the set must be non-NULL. The
subsequent ones can either be supplied, or can be left
as NULL, in which case the top 4 functions will be
called as appropriate to simulate them.

arg: An opaque argument passed in to each callback.

Exceptions will only be thrown if the underlying callback
functions throw them.

走一段路径，调用
每个给定集合中的适当回调函数
路径的一部分。

路径：行走的路径。

walker：要使用的回调函数集。 首先
集合中的 4 个回调指针必须为非 NULL。 这
后续的可以提供，也可以留下
作为 NULL，在这种情况下，前 4 个函数将是
适当调用以模拟它们。

arg：传递给每个回调的不透明参数。

仅当底层回调时才会抛出异常
函数抛出它们。

*/
void fz_walk_path(fz_context *ctx, const fz_path *path, const fz_path_walker *walker, void *arg);

/**
Create a new (empty) path structure.
创建一个新的（空）路径结构。
*/
fz_path *fz_new_path(fz_context *ctx);

/**
Increment the reference count. Returns the same pointer.

All paths can be kept, regardless of their packing type.

Never throws exceptions.
增加引用计数。 返回相同的指针。

可以保留所有路径，无论其打包类型如何。

从不抛出异常。

*/
fz_path *fz_keep_path(fz_context *ctx, const fz_path *path);

/**
Decrement the reference count. When the reference count hits
zero, free the path.

All paths can be dropped, regardless of their packing type.
Packed paths do not own the blocks into which they are packed
so dropping them does not free those blocks.

Never throws exceptions.

减少引用计数。 当引用计数达到
零，释放路径。

所有路径都可以删除，无论它们的打包类型如何。
打包路径不拥有打包它们的块
所以删除它们不会释放这些块。

从不抛出异常。

*/
void fz_drop_path(fz_context *ctx, const fz_path *path);

/**
Minimise the internal storage used by a path.

As paths are constructed, the internal buffers
grow. To avoid repeated reallocations they
grow with some spare space. Once a path has
been fully constructed, this call allows the
excess space to be trimmed.
最小化路径使用的内部存储。

构建路径时，内部缓冲区
生长。 为了避免重复重新分配，他们
增长一些空闲空间。 一旦路径有
已完全构建，此调用允许
多余的空间要修剪。

*/
void fz_trim_path(fz_context *ctx, fz_path *path);

/**
Return the number of bytes required to pack a path.
返回打包路径所需的字节数。
*/
int fz_packed_path_size(const fz_path *path);

/**
Pack a path into the given block.
To minimise the size of paths, this function allows them to be
packed into a buffer with other information. Paths can be used
interchangeably regardless of how they are packed.

pack: Pointer to a block of data to pack the path into. Should
be aligned by the caller to the same alignment as required for
a fz_path pointer.

max: The number of bytes available in the block.
If max < sizeof(fz_path) then an exception will
be thrown. If max >= the value returned by
fz_packed_path_size, then this call will never
fail, except in low memory situations with large
paths.

path: The path to pack.

Returns the number of bytes within the block used. Callers can
access the packed path data by casting the value of pack on
entry to be a fz_path *.

Throws exceptions on failure to allocate, or if
max < sizeof(fz_path).

Implementation details: Paths can be 'unpacked', 'flat', or
'open'. Standard paths, as created are 'unpacked'. Paths that
will pack into less than max bytes will be packed as 'flat',
unless they are too large (where large indicates that they
exceed some private implementation defined limits, currently
including having more than 256 coordinates or commands).

Large paths are 'open' packed as a header into the given block,
plus pointers to other data blocks.

Users should not have to care about whether paths are 'open'
or 'flat' packed. Simply pack a path (if required), and then
forget about the details.


将路径打包到给定的块中。
为了最小化路径的大小，此功能允许它们
与其他信息一起打包到缓冲区中。可以使用路径
无论它们如何包装，都可以互换。

pack：指向要打包路径的数据块的指针。应该
由调用者对齐到所需的相同对齐
fz_path 指针。

max：块中可用的字节数。
如果 max < sizeof(fz_path) 那么异常将
被抛出。如果 max >= 返回的值
fz_packed_pa​​th_size，那么这个调用永远不会
失败，除非在内存不足的情况下
路径。

path：打包的路径。

返回使用的块内的字节数。来电者可以
通过将 pack 的值转换为 on 来访问打包路径数据
条目为 fz_path *。

分配失败时抛出异常，或者如果
最大 < 大小（fz_path）。

实现细节：路径可以是“解包”、“扁平”或
'打开'。创建的标准路径是“解压缩的”。路径
将打包成小于最大字节将被打包为“平面”，
除非它们太大（大表明它们
超过一些私人实现定义的限制，目前
包括超过 256 个坐标或命令）。

大路径被“开放”打包为给定块的标题，
加上指向其他数据块的指针。

用户不必关心路径是否“开放”
或“扁平”包装。只需打包一个路径（如果需要），然后
忘记细节。

*/
size_t fz_pack_path(fz_context *ctx, uint8_t *pack, size_t max, const fz_path *path);

/**
Clone the data for a path.

This is used in preference to fz_keep_path when a whole
new copy of a path is required, rather than just a shared
pointer. This probably indicates that the path is about to
be modified.

path: path to clone.

Throws exceptions on failure to allocate.
克隆路径的数据。

当一个整体时，这优先于 fz_keep_path 使用
需要路径的新副本，而不仅仅是共享
指针。 这可能表明路径即将
被修改。

路径：克隆的路径。

分配失败时抛出异常。

*/
fz_path *fz_clone_path(fz_context *ctx, fz_path *path);

/**
Return the current point that a path has
reached or (0,0) if empty.

path: path to return the current point of.
返回路径具有的当前点
达到或 (0,0) 如果为空。

path：返回当前点的路径。

*/
fz_point fz_currentpoint(fz_context *ctx, fz_path *path);

/**
Append a ‘moveto’ command to a path.
This ‘opens’ a path.

path: The path to modify.

x, y: The coordinate to move to.

Throws exceptions on failure to allocate, or attempting to
modify a packed path.

将“moveto”命令附加到路径。
这“打开”了一条道路。

path：要修改的路径。

x, y：要移动到的坐标。

在分配失败或尝试分配时引发异常
修改打包路径。

*/
void fz_moveto(fz_context *ctx, fz_path *path, float x, float y);

/**
Append a ‘lineto’ command to an open path.

path: The path to modify.

x, y: The coordinate to line to.

Throws exceptions on failure to allocate, or attempting to
modify a packed path.

将“lineto”命令附加到开放路径。

path：要修改的路径。

x, y：线的坐标。

在分配失败或尝试分配时引发异常
修改打包路径。

*/
void fz_lineto(fz_context *ctx, fz_path *path, float x, float y);

/**
Append a ‘rectto’ command to an open path.

The rectangle is equivalent to:
	moveto x0 y0
	lineto x1 y0
	lineto x1 y1
	lineto x0 y1
	closepath

path: The path to modify.

x0, y0: First corner of the rectangle.

x1, y1: Second corner of the rectangle.

Throws exceptions on failure to allocate, or attempting to
modify a packed path.

将“rectto”命令附加到开放路径。

矩形等效于：
移动到 x0 y0
线到 x1 y0
线到 x1 y1
线到 x0 y1
近距离

path：要修改的路径。

x0, y0：矩形的第一个角。

x1, y1：矩形的第二个角。

在分配失败或尝试分配时引发异常
修改打包路径。

*/
void fz_rectto(fz_context *ctx, fz_path *path, float x0, float y0, float x1, float y1);

/**
Append a ‘quadto’ command to an open path. (For a
quadratic bezier).

path: The path to modify.

x0, y0: The control coordinates for the quadratic curve.

x1, y1: The end coordinates for the quadratic curve.

Throws exceptions on failure to allocate, or attempting to
modify a packed path.

将“quadto”命令附加到开放路径。 （为一个
二次贝塞尔曲线）。

path：要修改的路径。

x0, y0：二次曲线的控制坐标。

x1, y1：二次曲线的终点坐标。

在分配失败或尝试分配时引发异常
修改打包路径。

*/
void fz_quadto(fz_context *ctx, fz_path *path, float x0, float y0, float x1, float y1);

void fz_quadto(fz_context *ctx, fz_path *path, float x0, float y0, float x1, float y1);

/**
Append a ‘curveto’ command to an open path. (For a
cubic bezier).

path: The path to modify.

x0, y0: The coordinates of the first control point for the
curve.

x1, y1: The coordinates of the second control point for the
curve.

x2, y2: The end coordinates for the curve.

Throws exceptions on failure to allocate, or attempting to
modify a packed path.
将“curveto”命令附加到开放路径。 （为一个
三次贝塞尔）。

path：要修改的路径。

x0, y0：第一个控制点的坐标
曲线。

x1, y1：第二个控制点的坐标
曲线。

x2, y2：曲线的终点坐标。

在分配失败或尝试分配时引发异常
修改打包路径。

*/
void fz_curveto(fz_context *ctx, fz_path *path, float x0, float y0, float x1, float y1, float x2, float y2);

/**
Append a ‘curvetov’ command to an open path. (For a
cubic bezier with the first control coordinate equal to
the start point).

path: The path to modify.

x1, y1: The coordinates of the second control point for the
curve.

x2, y2: The end coordinates for the curve.

Throws exceptions on failure to allocate, or attempting to
modify a packed path.

将“curvetov”命令附加到开放路径。 （为一个
第一个控制坐标等于的三次贝塞尔曲线
起点）。

path：要修改的路径。

x1, y1：第二个控制点的坐标
曲线。

x2, y2：曲线的终点坐标。

在分配失败或尝试分配时引发异常
修改打包路径。

*/
void fz_curvetov(fz_context *ctx, fz_path *path, float x1, float y1, float x2, float y2);

/**
Append a ‘curvetoy’ command to an open path. (For a
cubic bezier with the second control coordinate equal to
the end point).

path: The path to modify.

x0, y0: The coordinates of the first control point for the
curve.

x2, y2: The end coordinates for the curve (and the second
control coordinate).

Throws exceptions on failure to allocate, or attempting to
modify a packed path.

将“curvetoy”命令附加到开放路径。 （为一个
第二个控制坐标等于的三次贝塞尔曲线
终点）。


path：要修改的路径。

x0, y0：第一个控制点的坐标
曲线。

x2, y2：曲线的终点坐标（和第二个
控制坐标）。

在分配失败或尝试分配时引发异常
修改打包路径。

*/
void fz_curvetoy(fz_context *ctx, fz_path *path, float x0, float y0, float x2, float y2);

/**
Close the current subpath.

path: The path to modify.

Throws exceptions on failure to allocate, attempting to modify
a packed path, and illegal path closes (i.e. closing a non open
path).

关闭当前子路径。

path：要修改的路径。

分配失败时抛出异常，尝试修改
一个压缩路径，非法路径关闭（即关闭一个非开放的
小路）。

*/
void fz_closepath(fz_context *ctx, fz_path *path);

/**
Transform a path by a given
matrix.

path: The path to modify (must not be a packed path).

transform: The transform to apply.

Throws exceptions if the path is packed, or on failure
to allocate.

通过给定的路径转换路径
矩阵。

path：要修改的路径（不能是打包路径）。

变换：要应用的变换。

如果路径已打包或失败则抛出异常
分配。

*/
void fz_transform_path(fz_context *ctx, fz_path *path, fz_matrix transform);

/**
Return a bounding rectangle for a path.

path: The path to bound.

stroke: If NULL, the bounding rectangle given is for
the filled path. If non-NULL the bounding rectangle
given is for the path stroked with the given attributes.

ctm: The matrix to apply to the path during stroking.

r: Pointer to a fz_rect which will be used to hold
the result.

Returns r, updated to contain the bounding rectangle.

返回路径的边界矩形。

路径：绑定的路径。

stroke: 如果为 NULL，则给出的边界矩形用于
填充的路径。 如果非 NULL 边界矩形
given 用于使用给定属性描边的路径。

ctm：在描边期间应用于路径的矩阵。

r：指向将用于保存的 fz_rect 的指针
结果。

返回 r，更新为包含边界矩形。

*/
fz_rect fz_bound_path(fz_context *ctx, const fz_path *path, const fz_stroke_state *stroke, fz_matrix ctm);

/**
Given a rectangle (assumed to be the bounding box for a path),
expand it to allow for the expansion of the bbox that would be
seen by stroking the path with the given stroke state and
transform.
给定一个矩形（假设是路径的边界框），
扩展它以允许扩展 bbox
通过用给定的笔画状态抚摸路径而看到的
转换。
*/
fz_rect fz_adjust_rect_for_stroke(fz_context *ctx, fz_rect rect, const fz_stroke_state *stroke, fz_matrix ctm);

/**
A sane ‘default’ stroke state.
理智的“默认”笔画状态。
*/
extern const fz_stroke_state fz_default_stroke_state;

/**
Create a new (empty) stroke state structure (with no dash
data) and return a reference to it.

Throws exception on failure to allocate.
创建一个新的（空的）笔画状态结构（没有破折号
数据）并返回对它的引用。

分配失败时抛出异常。

*/
fz_stroke_state *fz_new_stroke_state(fz_context *ctx);

/**
Create a new (empty) stroke state structure, with room for
dash data of the given length, and return a reference to it.

len: The number of dash elements to allow room for.

Throws exception on failure to allocate.

创建一个新的（空的）笔画状态结构，有空间
破折号给定长度的数据，并返回对它的引用。

len：要留出空间的破折号元素的数量。

分配失败时抛出异常。

*/
fz_stroke_state *fz_new_stroke_state_with_dash_len(fz_context *ctx, int len);

/**
Take an additional reference to a stroke state structure.

No modifications should be carried out on a stroke
state to which more than one reference is held, as
this can cause race conditions.
额外参考笔画状态结构。

不得对中风进行任何修改
持有多个引用的状态，如
这可能会导致竞争条件。

*/
fz_stroke_state *fz_keep_stroke_state(fz_context *ctx, const fz_stroke_state *stroke);

/**
Drop a reference to a stroke state structure, destroying the
structure if it is the last reference.
删除对笔画状态结构的引用，破坏
结构，如果它是最后一个引用。
*/
void fz_drop_stroke_state(fz_context *ctx, const fz_stroke_state *stroke);

/**
Given a reference to a (possibly) shared stroke_state structure,
return a reference to an equivalent stroke_state structure
that is guaranteed to be unshared (i.e. one that can
safely be modified).

shared: The reference to a (possibly) shared structure
to unshare. Ownership of this reference is passed in
to this function, even in the case of exceptions being
thrown.

Exceptions may be thrown in the event of failure to
allocate if required.

给定对（可能）共享 stroke_state 结构的引用，
返回对等效 stroke_state 结构的引用
保证不共享（即可以
安全地进行修改）。

共享：对（可能）共享结构的引用
取消共享。 传入此引用的所有权
到这个函数，即使在异常的情况下
抛出。

失败时可能会抛出异常
如果需要，分配。

*/
fz_stroke_state *fz_unshare_stroke_state(fz_context *ctx, fz_stroke_state *shared);

/**
Given a reference to a (possibly) shared stroke_state structure,
return a reference to a stroke_state structure (with room for a
given amount of dash data) that is guaranteed to be unshared
(i.e. one that can safely be modified).

shared: The reference to a (possibly) shared structure
to unshare. Ownership of this reference is passed in
to this function, even in the case of exceptions being
thrown.

Exceptions may be thrown in the event of failure to
allocate if required.

给定对（可能）共享 stroke_state 结构的引用，
返回一个对 stroke_state 结构的引用（有空间容纳一个
给定数量的破折号数据）保证不共享
（即可以安全修改的一个）。

共享：对（可能）共享结构的引用
取消共享。 传入此引用的所有权
到这个函数，即使在异常的情况下
抛出。

失败时可能会抛出异常
如果需要，分配。

*/
fz_stroke_state *fz_unshare_stroke_state_with_dash_len(fz_context *ctx, fz_stroke_state *shared, int len);

/**
Create an identical stroke_state structure and return a
reference to it.

stroke: The stroke state reference to clone.

Exceptions may be thrown in the event of a failure to
allocate.
创建一个相同的stroke_state结构并返回一个
参考它。

笔画：克隆的笔画状态参考。

失败时可能会抛出异常

分配。
*/
fz_stroke_state *fz_clone_stroke_state(fz_context *ctx, fz_stroke_state *stroke);

#endif