func (p *ImagePattern) ColorAt(x, y float64) RGBA {
	// Apply inverse transform: device-space -> image-space.
	imgPt := p.inverse.TransformPoint(Pt(x, y))
	lx := imgPt.X
	ly := imgPt.Y

	// Get image bounds.
	imgW, imgH := p.image.Bounds()

	// Determine pattern region.
	patternW := p.w
	patternH := p.h
	if patternW == 0 {
		patternW = imgW
	}
	if patternH == 0 {
		patternH = imgH
	}

	if p.clamp {
		// Clamp mode: out-of-bounds returns transparent.
		ix := int(lx)
		iy := int(ly)
		if ix < 0 || ix >= patternW || iy < 0 || iy >= patternH {
			return RGBA{}
		}
		ix += p.x
		iy += p.y
		r, g, b, a := p.image.GetRGBA(ix, iy)
		col := RGBA{
			R:	float64(r) / 255.0,
			G:	float64(g) / 255.0,
			B:	float64(b) / 255.0,
			A:	float64(a) / 255.0,
		}
		if p.opacity > 0 && p.opacity < 1.0 {
			col.A *= p.opacity
		}
		return col
	}

	// Wrap coordinates to pattern region (tiling).
	px := int(lx) % patternW
	py := int(ly) % patternH
	if px < 0 {
		px += patternW
	}
	if py < 0 {
		py += patternH
	}

	// Add source region offset.
	px += p.x
	py += p.y

	// Sample the image.
	r, g, b, a := p.image.GetRGBA(px, py)
	col := RGBA{
		R:	float64(r) / 255.0,
		G:	float64(g) / 255.0,
		B:	float64(b) / 255.0,
		A:	float64(a) / 255.0,
	}
	if p.opacity > 0 && p.opacity < 1.0 {
		col.A *= p.opacity
	}
	return col
}

func (c *Context) CreateImagePattern(img *ImageBuf, x, y, w, h int) Pattern {
	return &ImagePattern{
		image:		img,
		x:		x,
		y:		y,
		w:		w,
		h:		h,
		inverse:	Identity(),	// identity transform: device coords = image coords (tiling from origin)
	}
}

func (c *Context) CreateOffscreenTexture(width, height int) (gpucontext.TextureView, func()) {
	rc := c.gpuCtxOps()
	if rc == nil {
		return gpucontext.TextureView{}, nil
	}
	type offscreenCreator interface {
		CreateOffscreenTexture(w, h int) (gpucontext.TextureView, func())
	}
	if oc, ok := rc.(offscreenCreator); ok {
		return oc.CreateOffscreenTexture(width, height)
	}
	return gpucontext.TextureView{}, nil
}

func (c *Context) DrawGPUTexture(view gpucontext.TextureView, x, y float64, width, height int) {
	rc := c.gpuCtxOps()
	if rc == nil || view.IsNil() {
		return
	}
	defer c.setGPUClipRect()()

	ctm := c.totalMatrix()
	tl := ctm.TransformPoint(Pt(x, y))
	br := ctm.TransformPoint(Pt(x+float64(width), y+float64(height)))

	target := c.gpuRenderTarget()
	vpW := uint32(target.Width)	//nolint:gosec // viewport fits uint32
	vpH := uint32(target.Height)	//nolint:gosec // viewport fits uint32

	rc.QueueGPUTextureDraw(target, view,
		float32(tl.X), float32(tl.Y), float32(br.X-tl.X), float32(br.Y-tl.Y),
		1.0, vpW, vpH)
}

func (c *Context) DrawGPUTextureBase(view gpucontext.TextureView, x, y float64, width, height int) {
	rc := c.gpuCtxOps()
	if rc == nil || view.IsNil() {
		return
	}

	ctm := c.totalMatrix()
	tl := ctm.TransformPoint(Pt(x, y))
	br := ctm.TransformPoint(Pt(x+float64(width), y+float64(height)))

	target := c.gpuRenderTarget()
	vpW := uint32(target.Width)	//nolint:gosec // viewport fits uint32
	vpH := uint32(target.Height)	//nolint:gosec // viewport fits uint32

	rc.QueueBaseLayer(target, view,
		float32(tl.X), float32(tl.Y), float32(br.X-tl.X), float32(br.Y-tl.Y),
		1.0, vpW, vpH)
}

func (c *Context) DrawGPUTextureWithOpacity(view gpucontext.TextureView, x, y float64, width, height int, opacity float32) {
	rc := c.gpuCtxOps()
	if rc == nil || view.IsNil() {
		return
	}
	defer c.setGPUClipRect()()

	ctm := c.totalMatrix()
	tl := ctm.TransformPoint(Pt(x, y))
	br := ctm.TransformPoint(Pt(x+float64(width), y+float64(height)))

	target := c.gpuRenderTarget()
	vpW := uint32(target.Width)	//nolint:gosec // viewport fits uint32
	vpH := uint32(target.Height)	//nolint:gosec // viewport fits uint32

	rc.QueueGPUTextureDraw(target, view,
		float32(tl.X), float32(tl.Y), float32(br.X-tl.X), float32(br.Y-tl.Y),
		opacity, vpW, vpH)
}

func (c *Context) DrawImage(img *ImageBuf, x, y float64) {
	c.DrawImageEx(img, DrawImageOptions{
		X:		x,
		Y:		y,
		Interpolation:	InterpBilinear,
		Opacity:	1.0,
		BlendMode:	BlendNormal,
	})
}

func (c *Context) DrawImageCircular(img *ImageBuf, cx, cy, radius float64) {
	c.Push()
	c.DrawCircle(cx, cy, radius)
	c.Clip()

	// Draw image centered, scaled to fit the circle diameter.
	diameter := radius * 2
	c.DrawImageEx(img, DrawImageOptions{
		X:		cx - radius,
		Y:		cy - radius,
		DstWidth:	diameter,
		DstHeight:	diameter,
		Opacity:	1.0,
		BlendMode:	BlendNormal,
	})

	c.Pop()
}

func (c *Context) DrawImageEx(img *ImageBuf, opts DrawImageOptions) {
	// Default values
	if opts.Interpolation == 0 {
		opts.Interpolation = InterpBilinear
	}
	if opts.Opacity == 0 {
		opts.Opacity = 1.0
	}

	// Get source dimensions
	srcWidth, srcHeight := img.Bounds()
	srcX, srcY := 0, 0
	srcW, srcH := srcWidth, srcHeight
	if opts.SrcRect != nil {
		srcX = opts.SrcRect.Min.X
		srcY = opts.SrcRect.Min.Y
		srcW = opts.SrcRect.Dx()
		srcH = opts.SrcRect.Dy()
	}

	// Determine destination size in user coordinates (before transform).
	dstWidth := opts.DstWidth
	dstHeight := opts.DstHeight
	if dstWidth == 0 {
		dstWidth = float64(srcW)
	}
	if dstHeight == 0 {
		dstHeight = float64(srcH)
	}

	// Try GPU textured quad path first (Tier 3).
	// This avoids the SetFillPattern→Fill() path which triggers mid-frame
	// CPU flushes when GPU is active (the ImagePattern fallback problem).
	if c.tryGPUDrawImage(img, opts, srcX, srcY, srcW, srcH, dstWidth, dstHeight) {
		return
	}

	// Compute scale factors for the image pattern.
	// The pattern maps source pixels to destination pixels.
	scaleX := dstWidth / float64(srcW)
	scaleY := dstHeight / float64(srcH)

	// Compose the full forward transform: image-space -> device-space.
	//
	// The transform chain is:
	//   1. Scale source pixels to destination size: Scale(scaleX, scaleY)
	//   2. Position at destination: Translate(opts.X, opts.Y)
	//   3. Apply current CTM to device space: totalMatrix()
	//
	// Forward: device = totalMatrix * Translate(x,y) * Scale(sx,sy) * imageCoord
	// Inverse: imageCoord = inverse(totalMatrix * Translate(x,y) * Scale(sx,sy)) * device
	//
	// This follows the Cairo/Skia/tiny-skia pattern (see IMAGE-PATTERN-TRANSFORM-RESEARCH.md).
	patternTransform := c.totalMatrix().
		Multiply(Translate(opts.X, opts.Y)).
		Multiply(Scale(scaleX, scaleY))
	inverse := patternTransform.Invert()

	// Create image pattern with pre-computed inverse transform.
	pattern := &ImagePattern{
		image:		img,
		x:		srcX,
		y:		srcY,
		w:		srcW,
		h:		srcH,
		inverse:	inverse,
		opacity:	opts.Opacity,
		clamp:		true,	// Don't tile — clamp to image bounds
	}

	// Save current state (paint, path, transform).
	c.Push()

	// Set image pattern as fill source.
	c.SetFillPattern(pattern)

	// Draw rectangle at destination using the current transform.
	// DrawRectangle applies the transform, which is what we want.
	c.DrawRectangle(opts.X, opts.Y, dstWidth, dstHeight)

	// Fill the rectangle — the Fill() pipeline handles clipping automatically.
	_ = c.Fill()

	c.Pop()
}

func (c *Context) DrawImageRounded(img *ImageBuf, x, y, radius float64) {
	w, h := img.Bounds()
	fw := float64(w)
	fh := float64(h)

	c.Push()
	c.DrawRoundedRectangle(x, y, fw, fh, radius)
	c.Clip()
	c.DrawImage(img, x, y)
	c.Pop()
}

func ImageBufFromImage(img image.Image) *ImageBuf {
	return intImage.FromStdImage(img)
}

func LoadImage(path string) (*ImageBuf, error) {
	return intImage.LoadImage(path)
}

func LoadWebP(path string) (*ImageBuf, error) {
	return intImage.LoadWebP(path)
}

func NewImageBuf(width, height int, format ImageFormat) (*ImageBuf, error) {
	return intImage.NewImageBuf(width, height, format)
}

func (p *ImagePattern) SetAnchor(x, y float64) {
	p.anchorX = x
	p.anchorY = y
	p.rebuildInverse()
}

func (p *ImagePattern) SetClamp(clamp bool) {
	p.clamp = clamp
}

func (c *Context) SetFillPattern(pattern Pattern) {
	if sp, ok := pattern.(*SolidPattern); ok {
		c.paint.solidColor = sp.Color
		c.paint.isSolid = true
		c.paint.Brush = nil
		c.paint.Pattern = nil
		return
	}
	c.paint.Pattern = pattern
	c.paint.Brush = BrushFromPattern(pattern)
	c.paint.isSolid = false
}

func (p *ImagePattern) SetOpacity(opacity float64) {
	p.opacity = opacity
}

func (p *ImagePattern) SetScale(sx, sy float64) {
	p.scaleX = sx
	p.scaleY = sy
	p.rebuildInverse()
}

func (c *Context) SetStrokePattern(pattern Pattern) {
	if sp, ok := pattern.(*SolidPattern); ok {
		c.paint.solidColor = sp.Color
		c.paint.isSolid = true
		c.paint.Brush = nil
		c.paint.Pattern = nil
		return
	}
	c.paint.Pattern = pattern
	c.paint.Brush = BrushFromPattern(pattern)
	c.paint.isSolid = false
}

func (p *ImagePattern) SetTransform(m Matrix) {
	p.inverse = m.Invert()
}

type DrawImageOptions struct {
	// X, Y specify the top-left corner where the image will be drawn.
	X, Y	float64

	// DstWidth and DstHeight specify the dimensions to scale the image to.
	// If zero, the source dimensions are used (possibly from SrcRect).
	DstWidth	float64
	DstHeight	float64

	// SrcRect defines the source rectangle to sample from.
	// If nil, the entire source image is used.
	SrcRect	*image.Rectangle

	// Interpolation specifies the interpolation mode for sampling.
	// Default is InterpBilinear.
	Interpolation	InterpolationMode

	// Opacity controls the overall transparency of the source image (0.0 to 1.0).
	// 1.0 means fully opaque, 0.0 means fully transparent.
	// Default is 1.0.
	Opacity	float64

	// BlendMode specifies how to blend source and destination pixels.
	// Default is BlendNormal.
	BlendMode	BlendMode
}

type ImagePattern struct {
	image	*ImageBuf
	x, y	int	// source region offset within the image
	w, h	int	// source region size (0 = full image dimension)
	inverse	Matrix	// maps device-space -> image-space (pre-computed)
	opacity	float64	// opacity multiplier (0=transparent, 1=opaque; 0 means default=1)
	clamp	bool	// when true, out-of-bounds returns transparent instead of tiling

	// Legacy fields for SetAnchor/SetScale backward compatibility.
	// When these are used, rebuildInverse() computes the inverse from them.
	anchorX	float64
	anchorY	float64
	scaleX	float64	// horizontal scale factor (0 means 1.0)
	scaleY	float64	// vertical scale factor (0 means 1.0)
}