libharu 源码解析-SRC

libharu 源码解析-SRC

t4.h

提供的代码片段是CCITT T.4一维霍夫曼游程编码处理的C/C++实现的一部分，这种编码在传真传输和图像压缩中常见，尤其是在TIFF（标记图像文件格式）文件中。这段代码定义了两个数组(`HPDF_TIFFFaxWhiteCodes` 和 `HPDF_TIFFFaxBlackCodes`)，它们包含了白色和黑色游程的霍夫曼码及其长度和对应的游程长度。

以下是关键组件的分解：

### 预处理器指令和宏

- `#ifndef _T4_` 和 `#define _T4_`：这些是防止在多个源文件中多次包含此文件时使用的预处理器指令，作为包含保护。
- `#ifdef G3CODES`：这个条件编译指令检查`G3CODES`是否被定义。如果定义了，则将编译霍夫曼码表的实际代码；否则，它将使用对表的外部引用。

### 数据结构和常量

- `tableentry`：一个结构体，定义霍夫曼码条目的组成部分：
  - `length`：代码的位长度。
  - `code`：霍夫曼码本身。
  - `runlen`：该代码代表的游程长度（以比特为单位）。

- `EOL`：表示行结束码值的常量。
- 状态值如`G3CODE_EOL`、`G3CODE_INVALID`、`G3CODE_EOF`和`G3CODE_INCOMP`被定义来表示解码过程中的特殊情形或错误。

### 霍夫曼码表

- `HPDF_TIFFFaxWhiteCodes` 和 `HPDF_TIFFFaxBlackCodes`：这两个是`tableentry`结构的数组，定义了白色和黑色游程的霍夫曼码。每个条目对应一个特定的游程长度，片段中显示了前几个示例条目。

### 条件编译

- 根据`G3CODES`是否定义，霍夫曼表的实际代码将被包含在编译中，或者将使用对这些表的外部引用。

这段代码片段对于任何处理使用CCITT T.4压缩的TIFF图像或传真数据的软件来说都是至关重要的部分，提供了将压缩数据解码回其原始形式所需的数据结构和常量。

### 附加说明

- 这些霍夫曼码表按照特定顺序排列，使得可以通过游程长度或（游程长度除以64）加上固定偏移量直接索引到表中。
- 表格中的`G3CODE_INVALID`条目仅在状态生成期间使用（参见mkg3states.c）。

总之，这段代码是TIFF图像或传真数据中CCITT T.4压缩数据解码的关键部分，确保可以正确地从压缩流中恢复原始图像信息。

这段代码涉及到的是CCITT T.4标准下的一维霍夫曼编码（Huffman coding），它是TIFF文件格式中用于黑白图像压缩的一种方法。让我们更深入地理解一下这段代码是如何帮助解码压缩的TIFF图像数据的：

1. 霍夫曼编码原理

霍夫曼编码是一种可变长度的前缀编码技术，它的核心思想是给出现频率高的符号较短的编码，而给出现频率低的符号较长的编码。这样可以有效地减少数据的总编码长度，从而实现压缩。

在CCITT T.4标准中，霍夫曼编码被用于表示连续的黑色或白色像素的“游程”（run）。例如，连续的16个白色像素会被编码成一个特定的二进制序列，而不是分别编码每一个像素。

2. 代码中的霍夫曼码表

在代码片段中，HPDF_TIFFFaxWhiteCodes 和 HPDF_TIFFFaxBlackCodes 是霍夫曼码表，它们存储了每个游程对应的霍夫曼码、码长和游程长度。例如，HPDF_TIFFFaxWhiteCodes[0] 的 runlen 是 2，表示这个码代表的是长度为2的白色游程；length 是 3，表示这个霍夫曼码由3位组成；code 是 0，即这个霍夫曼码是 000。

3. 解码过程

当解码一个使用CCITT T.4标准压缩的TIFF图像时，解码器会读取压缩流中的霍夫曼码，并查找相应的游程长度。解码器通常会维护一个当前读取到的位的位置，并且会尝试匹配霍夫曼码表中的码字。

• 解码器从流中读取比特，并构建一个临时的码字。
• 它将这个码字与霍夫曼码表中的码字比较，直到找到一个匹配。
• 当找到匹配时，解码器就会知道这个码字所代表的游程长度，并在图像中放置相应数量的黑色或白色像素。
• 解码器然后更新读取位置，继续解码下一个霍夫曼码。

4. EOL 和 EOF

除了游程编码之外，EOL 和 EOF 是特殊的码字，分别表示“行结束”和“文件结束”。这些码字帮助解码器管理图像的边界和压缩流的结束。

总结

通过使用霍夫曼编码和精心设计的码表，TIFF图像中的连续像素游程可以被高效地编码和解码，从而实现数据的压缩和恢复。这段代码正是实现这一功能的关键所在，它确保了压缩流可以被正确解析，恢复出原始图像的信息。

---

hpdf_array.c

这段代码是Haru Free PDF Library的一部分，专门用于处理PDF中的数组对象。以下是对主要函数的解释：

1. `HPDF_Array_New`: 创建一个新的PDF数组对象。函数首先分配内存空间用于存储`HPDF_Array`结构体，初始化结构体成员，创建一个链表用于存放数组元素，最后返回新创建的数组对象指针。

2. `HPDF_Box_Array_New`: 创建一个用于存储矩形框（四个浮点数：左、底、右、顶坐标）的PDF数组对象。首先调用`HPDF_Array_New`创建数组对象，然后向数组中添加四个`HPDF_Real`类型的对象，分别表示矩形的四个坐标。

3. `HPDF_Array_Free`: 释放一个PDF数组对象。函数先清除数组中的所有元素，释放链表，再释放数组对象自身占用的内存。

4. `HPDF_Array_Write`: 将PDF数组对象写入到PDF流中。遍历数组中的所有元素，将它们转换为PDF文本格式并写入流中，最后写入结束标志`']'`。

5. `HPDF_Array_AddNumber`, `HPDF_Array_AddReal`, `HPDF_Array_AddNull`, `HPDF_Array_AddName`: 向PDF数组中添加不同类型的对象。首先创建指定类型的新对象，然后调用`HPDF_Array_Add`将对象加入数组。

6. `HPDF_Array_Add`: 添加任意对象到PDF数组中。检查对象有效性，判断对象类型是否允许直接拥有，以及数组容量是否已满。如果对象是间接对象，创建代理对象并加入数组。否则，直接加入数组。

7. `HPDF_Array_Items`: 返回数组中的元素个数。

8. `HPDF_Array_Insert`: 在数组中插入一个对象在指定目标对象之前。如果找不到目标对象，则不执行插入操作。

9. `HPDF_Array_GetItem`: 获取数组中指定索引处的对象，同时检查对象的类是否符合预期。

10. `HPDF_Array_Clear`: 清空数组中的所有元素。遍历数组，释放每个元素占用的内存，清空链表。

这些函数共同实现了PDF数组对象的创建、操作和销毁，是PDF文件生成和处理的重要组件。

hpdf_binary

`hpdf_binary.c` 是 Haru Free PDF Library 中的一部分，用于处理 PDF 文件中的二进制数据。以下是该文件中关键函数的解释：

1. `HPDF_Binary_New`: 这个函数用于创建一个新的二进制对象。它接收一个内存管理器 (`mmgr`) 和指向二进制数据的指针 (`value`) 及其长度 (`len`)。首先，它分配内存来存储 `HPDF_Binary_Rec` 结构体，并初始化结构体的成员。接着，它使用 `HPDF_Binary_SetValue` 函数设置二进制数据的值。如果设置失败，它会释放先前分配的内存并返回 `NULL`。

2. `HPDF_Binary_Write`: 这个函数用于将二进制对象写入到 PDF 流中。如果二进制数据长度为0，它将写入 `<>` 到流中；否则，它先写入 `<` 字符，然后通过 `HPDF_Stream_WriteBinary` 写入二进制数据，最后写入 `>` 字符。如果提供了加密对象 `e`，则数据在写入前会被加密。

3. `HPDF_Binary_SetValue`: 用于设置或更新二进制对象的数据。它首先检查数据长度是否超过限制，如果是，则返回错误。如果当前有数据，它会释放这些数据。然后，它分配新的内存来存储传入的二进制数据，并复制数据。如果内存分配失败，返回错误代码。

4. `HPDF_Binary_Free`: 用于释放二进制对象。它首先检查对象是否存在，然后释放与对象关联的二进制数据，最后释放二进制对象本身占用的内存。

5. `HPDF_Binary_GetLen` 和 `HPDF_Binary_GetValue`: 这两个函数分别用于获取二进制对象的长度和值。

整体而言，`hpdf_binary.c` 提供了创建、写入、读取、更新和释放 PDF 文档中的二进制数据的能力，这是生成和操作 PDF 文件时处理图像、字体或其他二进制资源的关键部分。

hpdf_boolean

`hpdf_boolean.c` 文件是 Haru Free PDF Library 的一部分，主要负责 PDF 文件中布尔类型数据的处理。下面是这个文件中两个关键函数的解析：

1. `HPDF_Boolean_New`: 这个函数用于创建一个新的布尔对象。它接收一个内存管理器 (`mmgr`) 和一个布尔值 (`value`) 作为参数。首先，它尝试从内存管理器分配足够的内存来存储一个 `HPDF_Boolean_Rec` 结构体。如果分配成功，它初始化这个结构体的对象头（`header`），将其对象类设置为 `HPDF_OCLASS_BOOLEAN` 并将传入的布尔值赋给 `value` 成员。如果分配失败，函数将返回 `NULL`。

2. `HPDF_Boolean_Write`: 这个函数用于将布尔对象写入 PDF 流中。它接收一个布尔对象 (`obj`) 和一个流对象 (`stream`)。根据布尔对象的值，它调用 `HPDF_Stream_WriteStr` 函数向流中写入 `"true"` 或 `"false"`。函数返回写入操作的状态码。

这两个函数一起提供了创建和写入 PDF 文件中布尔类型的机制。布尔值在 PDF 中可以用于控制文档的各种属性或状态，例如页面的显示模式、注解的可见性等。通过 `HPDF_Boolean_New` 创建布尔对象后，可以使用 `HPDF_Boolean_Write` 将其写入 PDF 文档的相应位置。

需要注意的是，Haru Library 使用内部的内存管理机制，这在 `HPDF_Boolean_New` 中通过 `HPDF_GetMem` 函数调用来体现。同时，错误处理和资源管理（如内存释放）通常由更高层次的函数或库用户负责。

hpdf_catalog.c

`hpdf_catalog.c` 文件是 Haru Free PDF Library 的一部分，用于处理 PDF 文档中的目录（Catalog）对象。目录对象是 PDF 文件的根对象，包含文档的所有高级属性和结构。下面是对关键函数的解释：

1. **HPDF_Catalog_New**: 创建一个新的目录对象。它接收一个内存管理器 (`mmgr`) 和一个交叉引用表 (`xref`)。函数首先创建一个字典对象，设置其为目录子类，然后将其添加到交叉引用表中。之后，它添加必要的元素，如类型（`Type`）和页面树（`Pages`）。

2. **HPDF_Catalog_GetRoot**: 获取目录中的页面树。它从目录对象中提取 `Pages` 键的值，该值应为页面树对象。

3. **HPDF_Catalog_GetNames / HPDF_Catalog_SetNames**: 分别用于获取和设置目录中的名称字典，该字典用于存储文档中的命名项目。

4. **HPDF_Catalog_GetPageLayout / HPDF_Catalog_SetPageLayout**: 获取和设置文档的页面布局。页面布局决定了文档在打开时的默认显示方式，如单页、双页、连续或并排显示。

5. **HPDF_Catalog_GetPageMode / HPDF_Catalog_SetPageMode**: 获取和设置文档的页面模式。页面模式决定了文档在打开时的初始视图，如使用大纲、缩略图或全屏模式。

6. **HPDF_Catalog_SetOpenAction**: 设置文档的打开动作。这可以是一个目的地，当文档打开时，将自动跳转到该目的地。

7. **HPDF_Catalog_Validate**: 检查目录对象的有效性，确保其对象类正确无误。

8. **HPDF_Catalog_AddPageLabel**: 向目录的页面标签数组中添加一个页面标签。页面标签允许为文档中的页面提供自定义标签，如罗马数字或字母。

9. **HPDF_Catalog_SetViewerPreference / HPDF_Catalog_GetViewerPreference**: 分别用于设置和获取查看器偏好设置，包括隐藏工具栏、菜单栏、窗口UI，以及适应窗口大小、居中窗口和打印缩放选项。

这些函数协同工作，使开发者能够控制和配置 PDF 文档的高级特性，如页面布局、打开行为和查看器设置，以满足具体的应用需求。