view release on metacpan or  search on metacpan

include/pdfmake_watermark.h  view on Meta::CPAN

/*
 * pdfmake_watermark.h — Watermarks and stamps.
 *
 * Provides APIs for adding watermarks and stamps to PDF pages:
 * - Text watermarks (DRAFT, CONFIDENTIAL, etc.)
 * - Image watermarks (logos, signatures)
 * - Page stamps (Bates numbering, headers/footers)
 * - Positioning (diagonal, centered, tiled, custom)
 * - Opacity control via ExtGState
 *
 * Implementation uses Form XObjects for efficiency and content stream
 * manipulation for underlay/overlay placement.
 *
 * Reference: ISO 32000-2:2020
 *   §8.4.5 Graphics State (transparency)
 *   §8.10 Form XObjects
 *   §14.11.6 Watermark Annotations
 */

#ifndef PDFMAKE_WATERMARK_H
#define PDFMAKE_WATERMARK_H

#include "pdfmake_types.h"
#include "pdfmake_doc.h"
#include "pdfmake_page.h"
#include "pdfmake_image.h"

#ifdef __cplusplus
extern "C" {
#endif

/*----------------------------------------------------------------------------
 * Position types
 *--------------------------------------------------------------------------*/

typedef enum {
    PDFMAKE_WM_POS_CENTER = 0,      /* Centered on page */
    PDFMAKE_WM_POS_DIAGONAL,        /* Diagonal from corner to corner */
    PDFMAKE_WM_POS_TILE,            /* Tiled across page */
    PDFMAKE_WM_POS_CUSTOM,          /* Custom x, y position */
    PDFMAKE_WM_POS_TOP_LEFT,
    PDFMAKE_WM_POS_TOP_CENTER,
    PDFMAKE_WM_POS_TOP_RIGHT,
    PDFMAKE_WM_POS_BOTTOM_LEFT,
    PDFMAKE_WM_POS_BOTTOM_CENTER,
    PDFMAKE_WM_POS_BOTTOM_RIGHT,
    PDFMAKE_WM_POS_LEFT_CENTER,
    PDFMAKE_WM_POS_RIGHT_CENTER
} pdfmake_wm_position_t;

/*----------------------------------------------------------------------------
 * Watermark options
 *--------------------------------------------------------------------------*/

typedef struct {
    pdfmake_wm_position_t position;   /* Positioning mode */
    double rotation;                   /* Rotation in degrees */
    double opacity;                    /* 0.0 (transparent) to 1.0 (opaque) */
    double scale;                      /* Scale factor (1.0 = original) */
    double x_offset;                   /* X offset from computed position */
    double y_offset;                   /* Y offset from computed position */
    int    as_overlay;                 /* 1 = on top, 0 = behind content */
    
    /* Text-specific options */
    const char *font_name;             /* Font name (e.g., "Helvetica-Bold") */
    double      font_size;             /* Font size in points */
    double      color[3];              /* RGB color (0.0-1.0 each) */
    
    /* Tile-specific options */
    double tile_spacing_x;             /* Horizontal spacing between tiles */
    double tile_spacing_y;             /* Vertical spacing between tiles */
} pdfmake_watermark_opts_t;

/*----------------------------------------------------------------------------
 * Stamp position type (alias for watermark position)
 *--------------------------------------------------------------------------*/

typedef pdfmake_wm_position_t pdfmake_stamp_position_t;

/*----------------------------------------------------------------------------
 * Stamp options
 *--------------------------------------------------------------------------*/

typedef struct {
    pdfmake_stamp_position_t position;  /* Position on page */
    double margin_x;                     /* Horizontal margin from edge */
    double margin_y;                     /* Vertical margin from edge */
    const char *font_name;               /* Font name */
    double font_size;                    /* Font size in points */
    double color[3];                     /* RGB color */
} pdfmake_stamp_opts_t;

/*----------------------------------------------------------------------------
 * Watermark structure
 *--------------------------------------------------------------------------*/

typedef enum {
    PDFMAKE_WM_TYPE_TEXT = 0,
    PDFMAKE_WM_TYPE_IMAGE
} pdfmake_wm_type_t;

typedef struct pdfmake_watermark {
    pdfmake_wm_type_t type;
    pdfmake_watermark_opts_t opts;
    
    union {
        struct {
            char *text;                /* Text content (owned) */
            double text_width;         /* Computed text width */
            double text_height;        /* Computed text height */
        } text;
        struct {
            uint32_t image_obj;        /* Image XObject number */
            double   width;            /* Image width */
            double   height;           /* Image height */
        } image;
    } data;
    
    uint32_t xobject_num;              /* Form XObject number (if created) */
    uint32_t extgstate_num;            /* ExtGState number for opacity */
} pdfmake_watermark_t;