vipsgen

vipsgen uses a multi-layered approach to transform the dynamic, variadic libvips C API into a type-safe, idiomatic Go API. The layers are:

1. Introspection Analysis: Uses GObject introspection to extract operation metadata, argument types, and enums from libvips.
2. C Layer (vips.c/vips.h): Generates two types of C wrappers:
   • Basic functions: Handle required arguments only (e.g., vipsgen_resize).
   • With options functions: Use VipsOperation to handle optional parameters via dynamic dispatch (e.g., vipsgen_resize_with_options).
3. Go Binding Layer (vips.go): Handles CGO complexities including C array/string management, memory cleanup, and error handling.
4. Go Method Layer (image.go): Provides the final idiomatic API. It uses an Options Pattern where methods on the *Image struct accept an options struct (e.g., ResizeOptions) to manage optional parameters.

This architecture ensures that Go developers interact with type-safe structs and enums rather than raw C pointers and variadic arguments.

libvips represents multi-frame images (like animated GIFs or WebP) as a single vertically stacked image. vipsgen provides metadata accessors and specialized multi-page helpers to handle these images efficiently.

Accessing Page Metadata

Use these methods to inspect the frames within a multi-page image:

• img.Pages(): Returns the number of frames.
• img.PageHeight(): Returns the height of a single frame in pixels.
• img.PageDelay(): Returns per-frame delays in milliseconds.
• img.Loop(): Returns the loop count (0 for infinite).

Multi-page Helpers

Standard operations like rotation or cropping cannot be applied to a stacked image in a single call. vipsgen provides optimized C helpers that loop over frames internally to avoid CGo overhead:

• img.RotMultiPage(angle): Rotates all frames.
• img.ExtractAreaMultiPage(left, top, width, height): Crops all frames to the same region.
• img.EmbedMultiPage(left, top, newWidth, newHeight, options): Pads/extends all frames to a new canvas.

// Rotate all frames
err = img.RotMultiPage(vips.AngleD90)

// Crop all frames to the same region
err = img.ExtractAreaMultiPage(left, top, width, height)

// Embed (pad/extend) all frames to a new canvas
err = img.EmbedMultiPage(left, top, newWidth, newHeight, &vips.EmbedMultiPageOptions{
    Extend:     vips.ExtendBackground,
    Background: []float64{0, 0, 0, 0},
})

vipsgen provides an idiomatic Go API by using options structs for operations that have optional parameters in libvips.

For example, to use the Resize method with specific parameters, you should use a ResizeOptions struct and the DefaultResizeOptions() helper to ensure all necessary fields are initialized.

// ResizeOptions optional arguments for vips_resize
type ResizeOptions struct {
    Kernel Kernel
    Gap    float64
    Vscale float64
}

// DefaultResizeOptions creates default value for vips_resize optional arguments
func DefaultResizeOptions() *ResizeOptions {
    return &ResizeOptions{
        Kernel: Kernel(5),
        Gap:    2,
    }
}

// Usage example
func example(img *vips.Image) error {
    opts := vips.DefaultResizeOptions()
    opts.Gap = 4.0 // Override a default
    return img.Resize(2.0, opts)
}

// ResizeOptions optional arguments for vips_resize
type ResizeOptions struct {
    Kernel Kernel
    Gap    float64
    Vscale float64
}

func DefaultResizeOptions() *ResizeOptions {
    return &ResizeOptions{
        Kernel: Kernel(5),
        Gap:    2,
    }
}

func (r *Image) Resize(scale float64, options *ResizeOptions) error {
    if options != nil {
        out, err := vipsgenResizeWithOptions(r.image, scale, options.Kernel, options.Gap, options.Vscale)
        if err != nil {
            return err
        }
        r.setImage(out)
        return nil
    }
    out, err := vipsgenResize(r.image, scale)
    if err != nil {
        return err
    }
    r.setImage(out)
    return nil
}

This example demonstrates fetching an image from the web, creating a streaming source, performing a thumbnail resize, adding a yellow border, and saving the result as a WebP file.

package main

import (
	"log"
	"net/http"

	"github.com/cshum/vipsgen/vips"
)

func main() {
	// Fetch an image from http.Get
	resp, err := http.Get("https://raw.githubusercontent.com/cshum/imagor/master/testdata/gopher.png")
	if err != nil {
		log.Fatalf("Failed to fetch image: %v", err)
	}
	defer resp.Body.Close()

	// Create source from io.ReadCloser
	source := vips.NewSource(resp.Body)
	defer source.Close() // source needs to remain available during image lifetime

	// Shrink-on-load via creating image from thumbnail source with options
	image, err := vips.NewThumbnailSource(source, 800, &vips.ThumbnailSourceOptions{
		Height: 1000,
		FailOn: vips.FailOnError, // Fail on first error
	})
	if err != nil {
		log.Fatalf("Failed to load image: %v", err)
	}
	defer image.Close() // always close images to free memory

	// Add a yellow border using vips_embed
	border := 10
	if err := image.Embed(
		border, border,
		image.Width()+border*2,
		image.Height()+border*2,
		&vips.EmbedOptions{
			Extend:     vips.ExtendBackground,       // extend with colour from the background property
			Background: []float64{255, 255, 0, 255}, // Yellow border
		},
	); err != nil {
		log.Fatalf("Failed to add border: %v", err)
	}

	log.Printf("Processed image: %dx%d\n", image.Width(), image.Height())

	// Save the result as WebP file with options
	err = image.Webpsave("resized-gopher.webp", &vips.WebpsaveOptions{
		Q:              85,   // Quality factor (0-100)
		Effort:         4,    // Compression effort (0-6)
		SmartSubsample: true, // Better chroma subsampling
	})
	if err != nil {
		log.Fatalf("Failed to save image as WebP: %v", err)
	}
	log.Println("Successfully saved processed images")
}