Documentation
¶
Overview ¶
Package filter provides image filter implementations for the scene graph.
This package contains enterprise-grade filter effects:
- Gaussian blur (separable, O(n) per radius)
- Drop shadow (blur + offset + colorize)
- Color matrix transformations
All filters are designed for:
- Zero-allocation hot paths where possible
- Cache-friendly memory access patterns
- SIMD-compatible data layouts
Performance targets (1080p):
- Blur (r=5): <5ms
- Blur (r=20): <15ms
- Drop Shadow: <10ms
- Color Matrix: <2ms
Index ¶
- func BoxKernel(radius int) []float32
- func CachedGaussianKernel(radius float64) []float32
- func GaussianKernel(radius float64) []float32
- func KernelCenter(kernelSize int) int
- func OptimalKernelSize(radius float64) int
- type BlurFilter
- type ColorMatrixFilter
- func NewBrightnessFilter(factor float32) *ColorMatrixFilter
- func NewColorMatrixFilter(matrix [20]float32) *ColorMatrixFilter
- func NewColorTintFilter(tint gg.RGBA) *ColorMatrixFilter
- func NewContrastFilter(factor float32) *ColorMatrixFilter
- func NewGrayscaleFilter() *ColorMatrixFilter
- func NewHueRotateFilter(degrees float32) *ColorMatrixFilter
- func NewIdentityColorMatrix() *ColorMatrixFilter
- func NewInvertFilter() *ColorMatrixFilter
- func NewOpacityFilter(factor float32) *ColorMatrixFilter
- func NewSaturationFilter(factor float32) *ColorMatrixFilter
- func NewSepiaFilter() *ColorMatrixFilter
- type DropShadowFilter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BoxKernel ¶
BoxKernel generates a 1D box (uniform) kernel for the given radius. All values are equal: 1/(2*radius+1).
Box blur is faster than Gaussian but produces blocky results. Three passes of box blur approximate Gaussian blur well.
func CachedGaussianKernel ¶
CachedGaussianKernel returns a cached Gaussian kernel for the radius. This is more efficient when the same radius is used repeatedly.
func GaussianKernel ¶
GaussianKernel generates a 1D Gaussian kernel for the given radius. The kernel is normalized so all values sum to 1.0.
The kernel size is computed as 2 * ceil(radius * 3) + 1, which covers 99.7% of the Gaussian distribution (3 standard deviations).
For radius <= 0, returns a single-element kernel [1.0] (identity).
func KernelCenter ¶
KernelCenter returns the center index of a kernel of the given size.
func OptimalKernelSize ¶
OptimalKernelSize returns the optimal kernel size for a given radius. This is useful for pre-allocating buffers.
Types ¶
type BlurFilter ¶
type BlurFilter struct {
// RadiusX is the horizontal blur radius in pixels.
RadiusX float64
// RadiusY is the vertical blur radius in pixels.
RadiusY float64
}
BlurFilter applies separable Gaussian blur to an image. The separable algorithm processes horizontal and vertical passes independently, achieving O(w*h*(rx+ry)) complexity instead of O(w*h*rx*ry).
func NewBlurFilter ¶
func NewBlurFilter(radius float64) *BlurFilter
NewBlurFilter creates a new blur filter with equal radius in both directions.
func NewBlurFilterXY ¶
func NewBlurFilterXY(radiusX, radiusY float64) *BlurFilter
NewBlurFilterXY creates a new blur filter with different X and Y radii. This allows for anisotropic (directional) blur effects.
func (*BlurFilter) Apply ¶
func (f *BlurFilter) Apply(src, dst *gg.Pixmap, bounds scene.Rect)
Apply applies the Gaussian blur to src and writes the result to dst. The operation uses a two-pass separable algorithm:
- Horizontal pass: convolve each row with 1D kernel
- Vertical pass: convolve each column with 1D kernel
func (*BlurFilter) ExpandBounds ¶
func (f *BlurFilter) ExpandBounds(input scene.Rect) scene.Rect
ExpandBounds returns the expanded bounds after blur application. Blur expands the output region by the kernel radius in all directions.
type ColorMatrixFilter ¶
type ColorMatrixFilter struct {
// Matrix is the 4x5 transformation matrix in row-major order.
// [0-4] = row 0 (R), [5-9] = row 1 (G), [10-14] = row 2 (B), [15-19] = row 3 (A)
Matrix [20]float32
}
ColorMatrixFilter applies a 4x5 color transformation matrix to an image. The transformation is:
[R'] [a00 a01 a02 a03 a04] [R]
[G'] = [a10 a11 a12 a13 a14] * [G]
[B'] [a20 a21 a22 a23 a24] [B]
[A'] [a30 a31 a32 a33 a34] [A]
[1]
The fifth column provides bias/offset values. Color values are in [0, 255] range during transformation, then clamped back to valid range.
func NewBrightnessFilter ¶
func NewBrightnessFilter(factor float32) *ColorMatrixFilter
NewBrightnessFilter creates a filter that adjusts brightness. factor: 0.0 = black, 1.0 = unchanged, 2.0 = twice as bright
func NewColorMatrixFilter ¶
func NewColorMatrixFilter(matrix [20]float32) *ColorMatrixFilter
NewColorMatrixFilter creates a color matrix filter with the given matrix.
func NewColorTintFilter ¶
func NewColorTintFilter(tint gg.RGBA) *ColorMatrixFilter
NewColorTintFilter creates a filter that tints the image with a color. The tint is blended with the original based on the color's alpha.
func NewContrastFilter ¶
func NewContrastFilter(factor float32) *ColorMatrixFilter
NewContrastFilter creates a filter that adjusts contrast. factor: 0.0 = gray, 1.0 = unchanged, 2.0 = high contrast
func NewGrayscaleFilter ¶
func NewGrayscaleFilter() *ColorMatrixFilter
NewGrayscaleFilter creates a filter that converts to grayscale. Uses Rec. 709 luminance weights.
func NewHueRotateFilter ¶
func NewHueRotateFilter(degrees float32) *ColorMatrixFilter
NewHueRotateFilter creates a filter that rotates hue by the given angle (in degrees).
func NewIdentityColorMatrix ¶
func NewIdentityColorMatrix() *ColorMatrixFilter
NewIdentityColorMatrix creates a color matrix filter that passes through unchanged.
func NewInvertFilter ¶
func NewInvertFilter() *ColorMatrixFilter
NewInvertFilter creates a filter that inverts colors.
func NewOpacityFilter ¶
func NewOpacityFilter(factor float32) *ColorMatrixFilter
NewOpacityFilter creates a filter that multiplies alpha by the given factor. factor: 0.0 = fully transparent, 1.0 = unchanged
func NewSaturationFilter ¶
func NewSaturationFilter(factor float32) *ColorMatrixFilter
NewSaturationFilter creates a filter that adjusts color saturation. factor: 0.0 = grayscale, 1.0 = unchanged, 2.0 = oversaturated
func NewSepiaFilter ¶
func NewSepiaFilter() *ColorMatrixFilter
NewSepiaFilter creates a filter that applies sepia tone effect.
func (*ColorMatrixFilter) Apply ¶
func (f *ColorMatrixFilter) Apply(src, dst *gg.Pixmap, bounds scene.Rect)
Apply applies the color matrix transformation to the image.
func (*ColorMatrixFilter) ExpandBounds ¶
func (f *ColorMatrixFilter) ExpandBounds(input scene.Rect) scene.Rect
ExpandBounds returns the input bounds unchanged (color matrix doesn't expand).
func (*ColorMatrixFilter) Multiply ¶
func (f *ColorMatrixFilter) Multiply(other *ColorMatrixFilter) *ColorMatrixFilter
Multiply returns a new filter that is the product of this filter and another. The result applies this filter first, then the other.
type DropShadowFilter ¶
type DropShadowFilter struct {
// OffsetX is the horizontal shadow offset in pixels.
OffsetX float64
// OffsetY is the vertical shadow offset in pixels.
OffsetY float64
// BlurRadius is the shadow blur radius in pixels.
BlurRadius float64
// Color is the shadow color (typically black with partial alpha).
Color gg.RGBA
}
DropShadowFilter creates a drop shadow effect beneath an image. The filter extracts the alpha channel, blurs it, colorizes it, and composites it under the original image with an offset.
func NewDropShadowFilter ¶
func NewDropShadowFilter(offsetX, offsetY, blurRadius float64, color gg.RGBA) *DropShadowFilter
NewDropShadowFilter creates a new drop shadow filter. Common usage: NewDropShadowFilter(3, 3, 5, gg.RGBA2(0, 0, 0, 0.5))
func NewSimpleDropShadow ¶
func NewSimpleDropShadow(offsetX, offsetY, blurRadius float64) *DropShadowFilter
NewSimpleDropShadow creates a drop shadow with default black color at 50% opacity.
func (*DropShadowFilter) Apply ¶
func (f *DropShadowFilter) Apply(src, dst *gg.Pixmap, bounds scene.Rect)
Apply applies the drop shadow filter. The algorithm:
- Extract alpha channel from source
- Apply Gaussian blur to alpha
- Colorize with shadow color
- Offset the shadow
- Composite shadow under original
func (*DropShadowFilter) ExpandBounds ¶
func (f *DropShadowFilter) ExpandBounds(input scene.Rect) scene.Rect
ExpandBounds returns the expanded bounds after shadow application. Shadow expands by offset + blur radius in all directions.
Source Files