# openprinting/cups-filters architecture

> Architecture diagram of the GitHub repository openprinting/cups-filters, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openprinting/cups-filters
- Repository: https://github.com/openprinting/cups-filters

## Overview

##### Project Type and Purpose
- This is an open-source printing-filter tool-chain for CUPS (Common UNIX Printing System).
- Its purpose is to provide a set of backends and filters that convert incoming print jobs (PDF, images, text, PCLm, etc.) into printer-specific output streams or raster formats, and to wrap error handling for CUPS backends.

##### High-Level Architecture Overview
a. Job Submission & Scheduler (CUPS daemon)
b. Filter Chain Layer (cups-filters)
c. Backend Layer & Driver/PPD Resources

##### Main Components
- CUPS Scheduler (external) – Accepts IPP jobs.
- Filter Chain:
– imagetopdf, texttopdf, pdftopdf, pdftoraster, pclmtoraster, universal, foomatic-rip, etc. (each in filter/).
– beh (backend error-handler wrapper in backend/beh.c).
- Driver Definitions (drv/*.drv and ppdfiles/*.ppd) – PPD templates and driver metadata.
- MIME Configuration (mime/*.convs, *.types) – Rules to select which filter to invoke.
- Backends (backend/parallel.c, serial.c, cupsfilters.drv) – Final transport layer (USB, socket, file).
- External Tools & Libraries: Ghostscript, Poppler, MuPDF, QPDF, libfontembed.

##### Relationships & Data Flow
1. Client submits job → CUPS Scheduler
2. Scheduler consults mime/*.convs to select first filter (e.g. PDF → pdftopdf).
3. Filters execute in a pipeline:
a. Convert images/text to PDF (imagetopdf, texttopdf)
b. Modify or paginate PDF (pdftopdf)
c. Rasterize for printing (pdftoraster, pclmtoraster)
d. (Optionally) wrap with foomatic-rip for proprietary drivers
4. Filter output is CUPS Raster or PCL stream → passed to backend.
5. beh wrapper optionally intercepts errors and retries or suppresses disabling.
6. Backend sends final byte stream to printer device or network URI.

##### Architectural Patterns & Principles
- Modular Filter Chain (pluggable CUPS filters)
- Pipeline Data Flow – each filter reads stdin, writes stdout
- Plugin/Convention-Based Integration via mime and PPD lookup
- Separation of Concerns: conversion (imagetopdf), PDF manipulation (pdftopdf), rasterization (pdftoraster), error handling (beh), transport (backend).
- External Tool Wrapping – Ghostscript, QPDF, Ghostscript devices are invoked where needed.

##### Technologies & Frameworks
- C language with Autotools build (configure.ac, Makefile.am, m4/*)
- CUPS Filter API (stdin/stdout interface, PPD parsing)
- libqpdf (PDF manipulation in pdftopdf)
- Ghostscript, Poppler, MuPDF (external rendering backends)
- libfontembed for text-to-PDF font embedding
- Shell scripts for test harness (filter/test.sh)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Job["Print Job (IPP)"]:::external
    Scheduler["CUPS Scheduler"]:::cups
    Job -->|"submits"| Scheduler

    subgraph "MIME Configuration"
      Convs["Filter Rules (*.convs)"]:::backends
      Types["MIME Types (*.types)"]:::backends
    end
    Scheduler -->|"consults"| Convs
    Scheduler -->|"consults"| Types

    subgraph "Filter Chain Layer"
      Img2PDF["Filter: imagetopdf"]:::filters
      Txt2PDF["Filter: texttopdf"]:::filters
      PDF2PDF["Filter: pdftopdf"]:::filters
      PDF2Raster["Filter: pdftoraster"]:::filters
      PCLm2Raster["Filter: pclmtoraster"]:::filters
      Universal["Filter: universal"]:::filters
      Foomatic["Filter: foomatic-rip"]:::filters
    end
    Convs --> Img2PDF
    Convs --> Txt2PDF
    Convs --> PDF2PDF
    Convs --> PDF2Raster
    Convs --> PCLm2Raster
    Convs --> Universal
    Convs --> Foomatic

    Img2PDF --> PDF2PDF
    Txt2PDF --> PDF2PDF
    PDF2PDF --> PDF2Raster
    PDF2Raster --> PCLm2Raster
    PCLm2Raster --> Foomatic
    Universal --> PDF2Raster

    subgraph "Backend Layer & Drivers"
      BehWrapper["Error-Handler Wrapper (beh)"]:::backends
      Parallel["Backend: parallel"]:::backends
      Serial["Backend: serial"]:::backends
      Drivers["Driver Metadata (cupsfilters.drv)"]:::backends
      CustomMedia["Custom Media Lines"]:::backends
      PPDs["PPD Templates"]:::backends
    end
    Foomatic --> BehWrapper
    BehaviorAlias(BehWrapper) --- Drivers
    BehWrapper --> Parallel
    BehWrapper --> Serial
    Drivers --> BehWrapper
    CustomMedia --> BehWrapper
    PPDs --> PDF2PDF

    Parallel -->|"sends bytes"| Printer["Printer Device/URI"]:::external
    Serial -->|"sends bytes"| Printer

    subgraph "External Tools/Libraries"
      GS["Ghostscript"]:::external
      Poppler["Poppler"]:::external
      MuPDF["MuPDF"]:::external
      QPDF["QPDF"]:::external
      FontEmbed["libfontembed"]:::external
    end
    PDF2PDF -.-> QPDF
    PDF2Raster -.-> GS
    Img2PDF -.-> Poppler
    Txt2PDF -.-> FontEmbed

    click Img2PDF "https://github.com/openprinting/cups-filters/blob/master/filter/imagetopdf.c"
    click Txt2PDF "https://github.com/openprinting/cups-filters/blob/master/filter/texttopdf.c"
    click PDF2PDF "https://github.com/openprinting/cups-filters/blob/master/filter/pdftopdf.c"
    click PDF2Raster "https://github.com/openprinting/cups-filters/blob/master/filter/pdftoraster.c"
    click PCLm2Raster "https://github.com/openprinting/cups-filters/blob/master/filter/pclmtoraster.c"
    click Universal "https://github.com/openprinting/cups-filters/blob/master/filter/universal.c"
    click Foomatic "https://github.com/openprinting/cups-filters/tree/master/filter/foomatic-rip/"
    click BehWrapper "https://github.com/openprinting/cups-filters/blob/master/backend/beh.c"
    click Parallel "https://github.com/openprinting/cups-filters/blob/master/backend/parallel.c"
    click Serial "https://github.com/openprinting/cups-filters/blob/master/backend/serial.c"
    click Drivers "https://github.com/openprinting/cups-filters/blob/master/drv/cupsfilters.drv"
    click CustomMedia "https://github.com/openprinting/cups-filters/tree/master/drv/custom-media-lines"
    click PPDs "https://github.com/openprinting/cups-filters/tree/master/ppdfiles/"
    click Convs "https://github.com/openprinting/cups-filters/blob/master/mime/*.convs"
    click Types "https://github.com/openprinting/cups-filters/blob/master/mime/cupsfilters.types"

    classDef cups fill:#ADD8E6,stroke:#000;
    classDef filters fill:#90EE90,stroke:#000;
    classDef backends fill:#FFA500,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
