PDF-image

#ifndef MUPDF_FITZ_IMAGE_H
#define MUPDF_FITZ_IMAGE_H

#include “mupdf/fitz/system.h”
#include “mupdf/fitz/context.h”
#include “mupdf/fitz/store.h”
#include “mupdf/fitz/pixmap.h”

#include “mupdf/fitz/buffer.h”
#include “mupdf/fitz/stream.h”
#include “mupdf/fitz/compressed-buffer.h”

/**
Images are storable objects from which we can obtain fz_pixmaps.
These may be implemented as simple wrappers around a pixmap, or
as more complex things that decode at different subsample
settings on demand.

图像是可存储的对象，我们可以从中获取 fz_pixmaps。
这些可以作为围绕像素图的简单包装器来实现，或者
作为在不同子样本解码的更复杂的东西
按需设置。

*/
typedef struct fz_image fz_image;
typedef struct fz_compressed_image fz_compressed_image;
typedef struct fz_pixmap_image fz_pixmap_image;

/**
Called to get a handle to a pixmap from an image.

image: The image to retrieve a pixmap from.

color_params: The color parameters (or NULL for defaults).

subarea: The subarea of the image that we actually care about
(or NULL to indicate the whole image).

trans: Optional, unless subarea is given. If given, then on
entry this is the transform that will be applied to the complete
image. It should be updated on exit to the transform to apply to
the given subarea of the image. This is used to calculate the
desired width/height for subsampling.

w: If non-NULL, a pointer to an int to be updated on exit to the
width (in pixels) that the scaled output will cover.

h: If non-NULL, a pointer to an int to be updated on exit to the
height (in pixels) that the scaled output will cover.

Returns a non NULL pixmap pointer. May throw exceptions.

调用以从图像获取像素图的句柄。

image：要从中检索像素图的图像。

color_params：颜色参数（或默认值为 NULL）。

subarea：我们真正关心的图像的子区域
（或 NULL 表示整个图像）。

trans：可选，除非给出分区。 如果给出，则在
条目 这是将应用于完整的转换
图像。 它应该在退出转换时更新以应用于
图像的给定分区。 这用于计算
子采样所需的宽度/高度。

w：如果非 NULL，则指向要在退出时更新的 int 的指针
缩放输出将覆盖的宽度（以像素为单位）。

h：如果非 NULL，则指向要在退出时更新的 int 的指针
缩放输出将覆盖的高度（以像素为单位）。

返回一个非 NULL 像素图指针。 可能会抛出异常。

*/
fz_pixmap *fz_get_pixmap_from_image(fz_context *ctx, fz_image *image, const fz_irect *subarea, fz_matrix *ctm, int *w, int *h);

/**
Increment the (normal) reference count for an image. Returns the
same pointer.

Never throws exceptions.
增加图像的（正常）引用计数。 返回
同一个指针。

从不抛出异常。

*/
fz_image *fz_keep_image(fz_context *ctx, fz_image *image);

/**
Decrement the (normal) reference count for an image. When the
total (normal + key) reference count reaches zero, the image and
its resources are freed.

Never throws exceptions.

减少图像的（正常）引用计数。 当。。。的时候
总（正常 + 键）引用计数达到零，图像和
它的资源被释放。

从不抛出异常。

*/
void fz_drop_image(fz_context *ctx, fz_image *image);

/**
Increment the store key reference for an image. Returns the same
pointer. (This is the count of references for an image held by
keys in the image store).

Never throws exceptions.

增加图像的存储密钥引用。 返回相同
指针。 （这是对图像的引用计数
图像存储中的键）。

从不抛出异常。

*/
fz_image *fz_keep_image_store_key(fz_context *ctx, fz_image *image);

/**
Decrement the store key reference count for an image. When the
total (normal + key) reference count reaches zero, the image and
its resources are freed.

Never throws exceptions.
减少图像的存储键引用计数。 当。。。的时候
总（正常 + 键）引用计数达到零，图像和
它的资源被释放。

从不抛出异常。

*/
void fz_drop_image_store_key(fz_context *ctx, fz_image *image);

/**
Function type to destroy an images data
when it’s reference count reaches zero.
销毁图像数据的函数类型
当它的引用计数达到零时。
*/
typedef void (fz_drop_image_fn)(fz_context *ctx, fz_image *image);

/**
Function type to get a decoded pixmap for an image.

im: The image to decode.

subarea: NULL, or the subarea of the image required. Expressed
in terms of a rectangle in the original width/height of the
image. If non NULL, this should be updated by the function to
the actual subarea decoded - which must include the requested
area!

w, h: The actual width and height that the whole image would
need to be decoded to.

l2factor: On entry, the log 2 subsample factor required. If
possible the decode process can take care of (all or some) of
this subsampling, and must then update the value so the caller
knows what remains to be done.

Returns a reference to a decoded pixmap that satisfies the
requirements of the request. The caller owns the returned
reference.


获取图像解码像素图的函数类型。

im：要解码的图像。

subarea: NULL，或所需图像的分区。 表达
在原始宽度/高度的矩形方面
图像。 如果非 NULL，这应该由函数更新为
解码的实际分区 - 其中必须包括请求的
区域！

w，h：整个图像的实际宽度和高度
需要解码为。

l2factor：进入时，需要 log 2 子样本因子。 如果
解码过程可能会处理（全部或部分）
这个子采样，然后必须更新值，以便调用者
知道还有什么要做。

返回对满足以下条件的解码像素图的引用
请求的要求。 调用者拥有返回的
参考。

*/
typedef fz_pixmap *(fz_image_get_pixmap_fn)(fz_context *ctx, fz_image *im, fz_irect *subarea, int w, int h, int *l2factor);

/**
Function type to get the given storage
size for an image.

Returns the size in bytes used for a given image.
获取给定存储的函数类型
图像的大小。

返回用于给定图像的大小（以字节为单位）。

*/
typedef size_t (fz_image_get_size_fn)(fz_context *, fz_image *);

/**
Internal function to make a new fz_image structure
for a derived class.

w,h: Width and height of the created image.

bpc: Bits per component.

colorspace: The colorspace (determines the number of components,
and any color conversions required while decoding).

xres, yres: The X and Y resolutions respectively.

interpolate: 1 if interpolation should be used when decoding
this image, 0 otherwise.

imagemask: 1 if this is an imagemask (i.e. transparent), 0
otherwise.

decode: NULL, or a pointer to to a decode array. The default
decode array is [0 1] (repeated n times, for n color components).

colorkey: NULL, or a pointer to a colorkey array. The default
colorkey array is [0 255] (repeated n times, for n color
components).

mask: NULL, or another image to use as a mask for this one.
A new reference is taken to this image. Supplying a masked
image as a mask to another image is illegal!

size: The size of the required allocated structure (the size of
the derived structure).

get: The function to be called to obtain a decoded pixmap.

get_size: The function to be called to return the storage size
used by this image.

drop: The function to be called to dispose of this image once
the last reference is dropped.

Returns a pointer to an allocated structure of the required size,
with the first sizeof(fz_image) bytes initialised as appropriate
given the supplied parameters, and the other bytes set to zero.


内部函数创建一个新的 fz_image 结构
对于派生类。

w,h：创建的图像的宽度和高度。

bpc：每个组件的位数。

颜色空间：颜色空间（确定组件的数量，
以及解码时所需的任何颜色转换）。

xres, yres：分别为 X 和 Y 分辨率。

interpolate: 1 如果解码时应该使用插值
此图像，否则为 0。

图像掩码：1 如果这是一个图像掩码（即透明），0
除此以外。

解码：NULL，或指向解码数组的指针。默认的
解码数组是 [0 1]（重复 n 次，对于 n 个颜色分量）。

colorkey: NULL，或指向 colorkey 数组的指针。默认的
colorkey 数组是 [0 255]（重复 n 次，对于 n 种颜色
组件）。

掩码：NULL，或用作此掩码的另一张图像。
对该图像进行了新的引用。供应蒙面
图像作为另一个图像的掩码是非法的！

size：所需分配结构的大小（大小为
派生结构）。

get：要调用以获取解码像素图的函数。

get_size：要调用的函数返回存储大小
此图像使用。

drop：调用一次处理此图像的函数
最后一个引用被删除。

返回指向所需大小的已分配结构的指针，
适当地初始化第一个 sizeof(fz_image) 字节
给定提供的参数，其他字节设置为零。

*/
fz_image *fz_new_image_of_size(fz_context *ctx,
int w,
int h,
int bpc,
fz_colorspace *colorspace,
int xres,
int yres,
int interpolate,
int imagemask,
float *decode,
int *colorkey,
fz_image *mask,
size_t size,
fz_image_get_pixmap_fn *get_pixmap,
fz_image_get_size_fn *get_size,
fz_drop_image_fn *drop);

#define fz_new_derived_image(CTX,W,H,B,CS,X,Y,I,IM,D,C,M,T,G,S,Z)
((T*)Memento_label(fz_new_image_of_size(CTX,W,H,B,CS,X,Y,I,IM,D,C,M,sizeof(T),G,S,Z),#T))

/**
Create an image based on
the data in the supplied compressed buffer.

w,h: Width and height of the created image.

bpc: Bits per component.

colorspace: The colorspace (determines the number of components,
and any color conversions required while decoding).

xres, yres: The X and Y resolutions respectively.

interpolate: 1 if interpolation should be used when decoding
this image, 0 otherwise.

imagemask: 1 if this is an imagemask (i.e. transparency bitmap
mask), 0 otherwise.

decode: NULL, or a pointer to to a decode array. The default
decode array is [0 1] (repeated n times, for n color components).

colorkey: NULL, or a pointer to a colorkey array. The default
colorkey array is [0 255] (repeated n times, for n color
components).

buffer: Buffer of compressed data and compression parameters.
Ownership of this reference is passed in.

mask: NULL, or another image to use as a mask for this one.
A new reference is taken to this image. Supplying a masked
image as a mask to another image is illegal!


创建基于图像
提供的压缩缓冲区中的数据。

w,h：创建的图像的宽度和高度。

bpc：每个组件的位数。

颜色空间：颜色空间（确定组件的数量，
以及解码时所需的任何颜色转换）。

xres, yres：分别为 X 和 Y 分辨率。

interpolate: 1 如果解码时应该使用插值
此图像，否则为 0。

imagemask: 1 如果这是一个图像掩码（即透明度位图
掩码），否则为 0。

解码：NULL，或指向解码数组的指针。默认的
解码数组是 [0 1]（重复 n 次，对于 n 个颜色分量）。

colorkey: NULL，或指向 colorkey 数组的指针。默认的
colorkey 数组是 [0 255]（重复 n 次，对于 n 种颜色
组件）。

buffer：压缩数据和压缩参数的缓冲区。
传入此引用的所有权。

掩码：NULL，或用作此掩码的另一张图像。
对该图像进行了新的引用。供应蒙面
图像作为另一个图像的掩码是非法的！

*/
fz_image *fz_new_image_from_compressed_buffer(fz_context *ctx, int w, int h, int bpc, fz_colorspace *colorspace, int xres, int yres, int interpolate, int imagemask, float *decode, int *colorkey, fz_compressed_buffer *buffer, fz_image *mask);

/**
Create an image from the given
pixmap.

pixmap: The pixmap to base the image upon. A new reference
to this is taken.

mask: NULL, or another image to use as a mask for this one.
A new reference is taken to this image. Supplying a masked
image as a mask to another image is illegal!
从给定的图像创建像素图。

像素图：图像所基于的像素图。 新参考
对此采取。

掩码：NULL，或用作此掩码的另一张图像。
对该图像进行了新的引用。 供应蒙面
图像作为另一个图像的掩码是非法的！

*/
fz_image *fz_new_image_from_pixmap(fz_context *ctx, fz_pixmap *pixmap, fz_image *mask);

/**
Create a new image from a
buffer of data, inferring its type from the format
of the data.
从一个新图像创建一个
数据缓冲区，从格式推断其类型
的数据。
*/
fz_image *fz_new_image_from_buffer(fz_context *ctx, fz_buffer *buffer);

/**
Create a new image from the contents
of a file, inferring its type from the format of the
data.
从内容创建一个新图像
的文件，从文件的格式推断其类型
数据。
*/
fz_image *fz_new_image_from_file(fz_context *ctx, const char *path);

/**
Internal destructor exposed for fz_store integration.
为 fz_store 集成公开的内部析构函数。
*/
void fz_drop_image_imp(fz_context *ctx, fz_storable *image);

/**
Internal destructor for the base image class members.

Exposed to allow derived image classes to be written.
基本图像类成员的内部析构函数。

公开以允许编写派生的图像类。

*/
void fz_drop_image_base(fz_context *ctx, fz_image *image);

/**
Decode a subarea of a compressed image. l2factor is the amount
of subsampling inbuilt to the stream (i.e. performed by the
decoder). If non NULL, l2extra is the extra amount of
subsampling that should be performed by this routine. This will
be updated on exit to the amount of subsampling that is still
required to be done.
解码压缩图像的子区域。 l2factor 是数量
内置于流中的子采样（即由
解码器）。 如果非 NULL，l2extra 是额外的数量
此例程应执行的子采样。 这会
在退出时更新为仍然存在的子采样量
需要完成。
*/
fz_pixmap *fz_decomp_image_from_stream(fz_context *ctx, fz_stream *stm, fz_compressed_image *image, fz_irect *subarea, int indexed, int l2factor, int *l2extra);

/**
Convert pixmap from indexed to base colorspace.

This creates a new bitmap containing the converted pixmap data.
将像素图从索引颜色空间转换为基本颜色空间。
这将创建一个包含转换后的像素图数据的新位图。

*/
fz_pixmap *fz_convert_indexed_pixmap_to_base(fz_context *ctx, const fz_pixmap *src);

/**
Convert pixmap from DeviceN/Separation to base colorspace.

This creates a new bitmap containing the converted pixmap data.
将像素图从 DeviceN/Separation 转换为基本色彩空间。

这将创建一个包含转换后的像素图数据的新位图。

*/
fz_pixmap *fz_convert_separation_pixmap_to_base(fz_context *ctx, const fz_pixmap *src);

/**
Return the size of the storage used by an image.
返回图像使用的存储大小。
*/
size_t fz_image_size(fz_context *ctx, fz_image *im);

/**
Structure is public to allow other structures to
be derived from it. Do not access members directly.
结构是公开的以允许其他结构
从中衍生出来。 不要直接访问成员。
*/
struct fz_image
{
fz_key_storable key_storable;
int w, h;
uint8_t n;
uint8_t bpc;
unsigned int imagemask:1;
unsigned int interpolate:1;
unsigned int use_colorkey:1;
unsigned int use_decode:1;
unsigned int invert_cmyk_jpeg:1;
unsigned int decoded:1;
unsigned int scalable:1;
fz_image mask;
int xres; / As given in the image, not necessarily as rendered /
int yres; / As given in the image, not necessarily as rendered */
fz_colorspace *colorspace;
fz_drop_image_fn *drop_image;
fz_image_get_pixmap_fn *get_pixmap;
fz_image_get_size_fn *get_size;
int colorkey[FZ_MAX_COLORS * 2];
float decode[FZ_MAX_COLORS * 2];
};

/**
Request the natural resolution
of an image.

xres, yres: Pointers to ints to be updated with the
natural resolution of an image (or a sensible default
if not encoded).

请求自然解决的图像。

xres, yres：指向要更新的整数的指针
图像的自然分辨率（或合理的默认值
如果未编码）。

*/
void fz_image_resolution(fz_image *image, int *xres, int *yres);

/**
Retrieve the underlying compressed data for an image.

Returns a pointer to the underlying data buffer for an image,
or NULL if this image is not based upon a compressed data
buffer.

This is not a reference counted structure, so no reference is
returned. Lifespan is limited to that of the image itself.
检索图像的底层压缩数据。

返回一个指向图像底层数据缓冲区的指针，
如果此图像不是基于压缩数据，则为 NULL
缓冲。

这不是引用计数结构，因此没有引用
回。 寿命仅限于图像本身的寿命。

*/
fz_compressed_buffer *fz_compressed_image_buffer(fz_context *ctx, fz_image *image);
void fz_set_compressed_image_buffer(fz_context *ctx, fz_compressed_image *cimg, fz_compressed_buffer *buf);

/**
Retrieve the underlying fz_pixmap for an image.

Returns a pointer to the underlying fz_pixmap for an image,
or NULL if this image is not based upon an fz_pixmap.

No reference is returned. Lifespan is limited to that of
the image itself. If required, use fz_keep_pixmap to take
a reference to keep it longer.
检索图像的底层 fz_pixmap。

返回一个指向图像底层 fz_pixmap 的指针，
如果此图像不是基于 fz_pixmap，则为 NULL。

不返回引用。 寿命仅限于
图像本身。 如果需要，使用 fz_keep_pixmap 取
一个参考以保持更长时间。

*/
fz_pixmap *fz_pixmap_image_tile(fz_context *ctx, fz_pixmap_image *cimg);
void fz_set_pixmap_image_tile(fz_context *ctx, fz_pixmap_image *cimg, fz_pixmap *pix);

/* Implementation details: subject to change. */

/**
Exposed for PDF.
*/
fz_pixmap *fz_load_jpx(fz_context *ctx, const unsigned char *data, size_t size, fz_colorspace *cs);

/**
Exposed for CBZ.
*/
int fz_load_tiff_subimage_count(fz_context *ctx, const unsigned char *buf, size_t len);
fz_pixmap *fz_load_tiff_subimage(fz_context *ctx, const unsigned char *buf, size_t len, int subimage);
int fz_load_pnm_subimage_count(fz_context *ctx, const unsigned char *buf, size_t len);
fz_pixmap *fz_load_pnm_subimage(fz_context *ctx, const unsigned char *buf, size_t len, int subimage);
int fz_load_jbig2_subimage_count(fz_context *ctx, const unsigned char *buf, size_t len);
fz_pixmap *fz_load_jbig2_subimage(fz_context *ctx, const unsigned char *buf, size_t len, int subimage);
int fz_load_bmp_subimage_count(fz_context *ctx, const unsigned char *buf, size_t len);
fz_pixmap *fz_load_bmp_subimage(fz_context *ctx, const unsigned char *buf, size_t len, int subimage);

#endif