drawing

type Backend interface {
	DrawContext
	// Raster 返回当前后端绘制的全部内容对应的 RGBA 图像。
	Raster() *image.RGBA
}

type BackendFactory func(width, height float64, resolution geom.Resolution) (Backend, error)

type CTColor struct {
	Value    color.RGBA
	HasValue bool
	Gradient geom.Gradient
}

type DrawContext interface {
	// Push/Pop 保存并恢复当前样式与变换。
	Push()
	Pop()

	// Translate/Scale/Rotate 修改当前变换（文档坐标 → 设备坐标）。
	Translate(x, y float64)
	Scale(sx, sy float64)
	Rotate(deg float64)

	// CurrentMatrix 返回当前完整矩阵（用于把预渲染的离屏图按正确位置贴回）。
	CurrentMatrix() geom.Matrix

	// SetFillColor 设置纯色填充。SetFillGradient 设置渐变填充。
	SetFillColor(c color.Color)
	SetFillGradient(g geom.Gradient)

	// SetFillPaint 设置填充画笔（颜色或渐变）。
	SetFillPaint(paint geom.Paint)

	// ClearFill 清除填充。
	ClearFill()

	// SetStrokeColor 设置纯色描边。SetStrokeGradient 设置描边渐变。
	SetStrokeColor(c color.Color)
	SetStrokeGradient(g geom.Gradient)

	// SetStrokePaint 设置描边画笔（颜色或渐变）。
	SetStrokePaint(paint geom.Paint)

	// ClearStroke 清除描边。
	ClearStroke()

	// CopyStrokeToFill 把当前描边样式复制为填充样式。
	CopyStrokeToFill()

	// SetStrokeWidth 设置描边宽度。SetDashes 设置虚线数组。
	SetStrokeWidth(w float64)
	SetDashes(offset float64, dashes ...float64)
	SetStrokeCapper(cap geom.Capper)
	SetStrokeJoiner(join geom.Joiner)

	// StrokeWidth/StrokeCapper/StrokeJoiner 读回当前描边样式。
	StrokeWidth() float64
	StrokeCapper() geom.Capper
	StrokeJoiner() geom.Joiner

	// SetFillRule 设置填充规则（geom.NonZero / geom.EvenOdd）。
	SetFillRule(rule geom.FillRule)

	// DrawPath 按当前样式绘制路径（x,y 为路径的平移到画布的偏移）。
	DrawPath(x, y float64, p *geom.Path)

	// TextPath 绘制字形轮廓路径（baseline 位于 (0,0)，后端平移到 (x,y)）。
	TextPath(p *geom.Path, x, y float64)

	// DrawImage 绘制图片：dpmm 是源图像素到画布单位（mm）的换算。
	DrawImage(img image.Image, x, y float64, dpmm float64)

	// RenderImage 按绝对设备矩阵绘制预渲染图片。
	RenderImage(img image.Image, m geom.Matrix)
}

type FontEngine interface {
	// LoadFont 解析指定字体资源并返回字体族句柄。
	LoadFont(id models.StRefID) (FontFamily, error)
	// FaceObject 为字体族与文字对象创建字体面。
	FaceObject(family FontFamily, object models.TextObject, fill *CTColor) FontFace
	// RenderLock 返回串行化该字体族渲染的互斥锁。
	RenderLock(family FontFamily) *sync.Mutex
	// RegisterPageGlyphs 扫描页面文字并登记 Unicode→字形映射。
	RegisterPageGlyphs(doc *parser.Document, page *parser.Page, content *models.PageContent)
	// UseFallbackFont 使引擎在缺失字体时使用已全局注册的回退字体族。
	UseFallbackFont(family string) error
	// RemoveFallbackFont 取消先前登记的回退字体族，使缺失字体恢复内嵌/默认字体。
	RemoveFallbackFont(family string)
	// FallbackFontFamily 返回为文档字体选择的外部字体族。
	FallbackFontFamily(id models.StRefID) string
	// HasLoadedEmbeddedFont 判断文档字体是否解析为可用且已加载的内嵌字体。
	HasLoadedEmbeddedFont(id models.StRefID) bool
}

type FontFace interface {
	// ToPath 返回按字体整形后的单行文本轮廓路径（y 向上字号坐标系）。
	ToPath(value string) *geom.Path
	// DirectPath 返回按字形 ID 直接映射的轮廓路径；无法映射时返回 nil。
	DirectPath(value string) *geom.Path
	// TextWidth 返回文本的排版宽度（毫米）。
	TextWidth(value string) float64
	// GlyphIndex 返回 Unicode 码位对应的字形 ID；缺失返回 0。
	GlyphIndex(r rune) uint16
	// IsCFF 判断底层字体是否为 CFF 轮廓。
	IsCFF() bool
	// Fill 返回字体面携带的画笔（颜色或渐变）。
	Fill() geom.Paint
	// Size 返回字号（点）。
	Size() float64
	// ShapedRun 返回引擎整形的单行文本；不支持时返回 nil。
	ShapedRun(value string) TextRun
}

type FontFamily interface {
	Name() string
}

type FontStyle int

type PDFDocument interface {
	AddPage(page VectorSurface) error
	Close() error
}

type PDFOptions struct {
	Compress    bool // 压缩内容流
	SubsetFonts bool // 子集化 TrueType 字体
	LossyImages bool // 图片使用有损编码
}

type SVGScene interface {
	// Width/Height 返回 SVG 的原始画布尺寸（用户单位）。
	Width() float64
	Height() float64
	// Rasterize 按分辨率栅格化为标准图像。
	Rasterize(resolution geom.Resolution) image.Image
	// RenderVector 尝试以矢量方式嵌入当前绘制上下文，返回是否完成。
	RenderVector(ctx any, m geom.Matrix) bool
}

type TextRun interface{}

type VectorSurface interface {
	// Width/Height 返回页面物理尺寸（mm）。
	Width() float64
	Height() float64
	// Write 以 format 指定的矢量格式写出单页内容，支持 "svg"/"eps"/"tex"。
	Write(w io.Writer, format string) error
	// Rasterize 按分辨率把页面栅格化为标准 RGBA。
	Rasterize(resolution geom.Resolution) *image.RGBA
}