PDF-Writer

There are three primary ways to use PDF-Writer in your own C++ projects:

Option 1: CMake FetchContent (Recommended)

Automatically downloads and integrates the library during the configuration step. This is the easiest way to manage the dependency.

Option 2: find_package

Use this if you have already installed PDF-Writer on your system.

Option 3: Copy Sources

Manually copy the PDFWriter source folder into your project and include it in your build system.

# Option 1: FetchContent
include(FetchContent)
FetchContent_Declare(
  PDFHummus
  GIT_REPOSITORY https://github.com/galkahana/PDF-Writer.git
  GIT_TAG        v4.6.2
  FIND_PACKAGE_ARGS
)
FetchContent_MakeAvailable(PDFHummus)
target_link_libraries(YourTarget PDFHummus::PDFWriter)

To build PDF-Writer from source, use CMake to configure the project and then build it using your preferred compiler. Ensure you have a compatible compiler (Visual Studio on Windows, GCC/Clang on Linux/macOS) and CMake installed. If you require PDF 2.0 encryption, ensure OpenSSL is available; otherwise, you can disable it via CMake options.

Quick Start Build Sequence

1. Create a build directory.
2. Configure with CMake.
3. Build the project in Release mode.
4. (Optional) Run tests using ctest.
5. (Optional) Install to a local prefix.

# Build
mkdir build && cd build
cmake ..
cmake --build . --config Release

# Test
ctest --test-dir . -C Release

# Install
cmake --install . --prefix ./install --config Release

gxvalid is a module used to validate TrueType GX tables, which are collections of additional tables in TrueType fonts used by Apple Advanced Typography (AAT) and QuickDraw GX Text. It also validates extended kern tables used for AAT.

Usage Patterns

• Library Integration: You can link gxvalid with your own program. By validating a font file with gxvalid before running your layout engine, you can reduce the amount of error-checking code required within the engine itself.
• Stand-alone Validator: You can use gxvalid as a standalone font validator. The ftvalid test program (included in the ft2demo bundle) calls gxvalid internally, making it useful for font developers.

The driver supports an extension to the BDF format (used by tools like xmbdfed and Microsoft's SBIT) that allows for anti-aliased bitmaps. This extension adds a fourth field to the SIZE keyword specifying the bits per pixel (bpp).

Supported bpp values:

• 1: Default (1 bit per pixel bitmap).
• 2: 4 gray levels.
• 4: 16 gray levels.
• 8: 256 gray levels.

The driver returns either a 1-bit per pixel bitmap or an 8-bit per pixel pixmap depending on the bpp value provided in the font file.

gxvalid is designed to be permissive, continuing validation even when encountering broken GX tables, similar to how Apple's rendering engines behave. The behavior depends on the configured validation level:

• FT_VALIDATE_DEFAULT: Warns about errors and attempts a fallback procedure or continues validation.
• FT_VALIDATE_TIGHT: Warns and may ignore certain segments or abort on specific errors (like invalid feature numbers in some cases).
• FT_VALIDATE_PARANOID: Aborts immediately upon finding errors (e.g., too-short LookupTable format 0, broken prop version, or invalid feature numbers).

You can customize the PDF-Writer build by passing specific flags to CMake. This is useful for reducing dependencies or disabling specific image format support.

Example of disabling bundled dependencies: cmake .. -DUSE_BUNDLED=FALSE

A known limitation of the BDF driver is that the entire font is loaded into memory at once, which can be inefficient for large fonts.

To avoid high memory usage, convert your BDF fonts to the PCF (Portable Compiled Format) format using the bdftopcf utility. The FreeType PCF driver supports incremental glyph loading, which is more memory-efficient than the BDF driver.

When compiling ftrandom, it is recommended to use debugging tools to catch memory issues or library errors:

1. Valgrind: Run ftrandom within valgrind to detect memory leaks and invalid accesses.
2. Sanitizers: Compile FreeType with sanitizer flags (provided by gcc or clang) and then link it with ftrandom to catch runtime errors.