PDF 프리미티브

개요

pdf 패키지 (Layer 1)는 저수준 PDF 프리미티브를 제공합니다. 대부분의 사용자는 이 패키지에서 색상 함수만 필요합니다 — 나머지는 레이아웃 엔진 내부에서 사용됩니다.

import "github.com/gpdf-dev/gpdf/pdf"

색상

색상은 pdf 패키지에서 가장 일반적으로 사용되는 타입입니다.

색상 생성자

// RGB (float values 0.0 – 1.0)
pdf.RGB(1.0, 0.5, 0.0)     // Orange

// Hex (uint32)
pdf.RGBHex(0xFF6B6B)       // Coral
pdf.RGBHex(0x1A237E)       // Dark blue

// Grayscale (0.0 = black, 1.0 = white)
pdf.Gray(0.0)              // Black
pdf.Gray(0.5)              // Medium gray
pdf.Gray(1.0)              // White

// CMYK (for print)
pdf.CMYK(0, 1, 1, 0)      // Red in CMYK

미리 정의된 색상

pdf.Black    // Gray(0)
pdf.White    // Gray(1)
pdf.Red      // RGB(1, 0, 0)
pdf.Green    // RGB(0, 1, 0)
pdf.Blue     // RGB(0, 0, 1)
pdf.Yellow   // RGB(1, 1, 0)
pdf.Cyan     // RGB(0, 1, 1)
pdf.Magenta  // RGB(1, 0, 1)

색상 사용

색상은 TextColor() 및 BgColor() 텍스트 옵션과 함께 사용됩니다:

c.Text("Red on yellow",
    template.TextColor(pdf.Red),
    template.BgColor(pdf.Yellow),
)

테이블/선 옵션에도 사용됩니다:

// Table header
template.TableHeaderStyle(
    template.TextColor(pdf.White),
    template.BgColor(pdf.RGBHex(0x1A237E)),
)

// Line color
template.LineColor(pdf.Blue)

색 공간

type ColorSpace int

const (
    ColorSpaceRGB  ColorSpace = iota
    ColorSpaceGray
    ColorSpaceCMYK
)

Color 타입

type Color struct {
    R, G, B float64     // RGB components (0.0 – 1.0)
    A       float64     // Alpha or K (for CMYK)
    Space   ColorSpace
}

Writer (고급)

PDF Writer는 저수준 PDF 객체 생성을 처리합니다. 대부분의 사용자는 이것을 직접 사용할 필요가 없습니다.

type Writer struct {}

func NewWriter(w io.Writer) *Writer
func (pw *Writer) AllocObject() ObjectRef
func (pw *Writer) WriteObject(ref ObjectRef, obj Object) error
func (pw *Writer) RegisterFont(name string, data []byte) error
func (pw *Writer) AddPage(page *PageContent) error
func (pw *Writer) Close() error
func (pw *Writer) SetDocumentInfo(info DocumentInfo)

PDF 객체 (고급)

저수준 PDF 객체 타입:

// Scalar types
type Name string
type LiteralString string
type HexString string
type Integer int64
type Real float64
type Boolean bool
type Null struct{}

// Composite types
type Dict map[string]Object
type Array []Object

// Stream (content, images, fonts)
type Stream struct {
    Data       []byte
    Dictionary Dict
}

// Object reference
type ObjectRef struct {
    Number     int
    Generation int
}

폰트 패키지 (고급)

pdf/font 서브 패키지는 TrueType 폰트 파싱 및 서브셋팅을 처리합니다:

import "github.com/gpdf-dev/gpdf/pdf/font"

// Parse a TrueType font
ttf, err := font.ParseTrueType(data)

// Get font name and metrics
name := ttf.Name()
metrics := ttf.Metrics()  // Ascender, Descender, CapHeight, XHeight

// Create a subset with only used glyphs
subset, err := ttf.Subset(runes)

// Measure text width
width := font.MeasureString(ttf, "Hello", 12.0)

// Break text into lines
lines := font.LineBreak(ttf, text, 12.0, maxWidth)

아키텍처

Layer 3: template ─── Builder API, JSON Schema, Components
    │
    ▼
Layer 2: document ─── Nodes, Box Model, Layout Engine
    │
    ▼
Layer 1: pdf ──────── Writer, Streams, Fonts, Images
    │
    ▼
          io.Writer (file, HTTP response, buffer...)

각 레이어는 아래 레이어에만 의존합니다 — 위쪽으로는 절대 의존하지 않습니다.