API Reference

Complete documentation of all public classes, protocols, and functions in the PixelFlux framework.

Core Protocol

Filter

The foundational protocol that all filters implement. Defines the contract for GPU-accelerated image processing.

public protocol Filter {
  func process(_ input: MTLTexture) throws -> MTLTexture
}

Description: Any type conforming to Filter can process Metal textures on the GPU. This is the base for all custom filters.

Methods

process(_:) MTLTexture → MTLTexture Processes an input GPU texture and returns the filtered output texture. Throws PixelFluxError if processing fails.

Built-in Filters

BrightnessFilter

Adjusts image brightness by adding a constant offset to pixel color values.

public final class BrightnessFilter: Filter {
  public init(brightness: Float) throws
  public var brightness: Float
  public func apply(to inputImage: UIImage) throws -> UIImage?
  public func process(_ input: MTLTexture) throws -> MTLTexture
}

Initialization

init(brightness:)

brightness Float Brightness adjustment value. Range: -1.0 (darker) to 1.0 (brighter). Default: 0.0 (no change). Can throw PixelFluxError.bufferCreationFailed.

Properties

brightness Float The brightness adjustment value used by this filter instance (read-only after initialization).

Methods

apply(to:)

Convenience method for applying the filter to a UIImage.

inputImage UIImage The source image to filter.

Returns: A new UIImage with brightness applied, or nil on error.

Throws: PixelFluxError if texture creation or processing fails.

Example

let originalImage = UIImage(named: "photo")!

do {
  let brightFilter = try BrightnessFilter(brightness: 0.3)
  let brightResult = try brightFilter.apply(to: originalImage)
  imageView.image = brightResult
} catch {
  print("Brightness filter error:", error)
}

PassthroughFilter

Identity filter that returns an unmodified image. Useful for testing and verifying the GPU pipeline.

public final class PassthroughFilter: Filter {
  public init() throws
  public func apply(to inputImage: UIImage) throws -> UIImage?
  public func process(_ input: MTLTexture) throws -> MTLTexture
}

Initialization

init()

Initializes the passthrough filter. Can throw PixelFluxError.commandBufferFailed if GPU pipeline setup fails.

Methods

apply(to:)

Applies the passthrough filter to a UIImage and returns it unmodified (after GPU processing).

inputImage UIImage The source image.

Returns: The input image after GPU processing, or nil on error.

Example

let filter = try PassthroughFilter()
let result = try filter.apply(to: image)
imageView.image = result

Public API

PixelFluxEngine

Main singleton providing convenient access to PixelFlux filters. Named PixelFluxEngine to avoid shadowing the PixelFlux module name, which would break Swift binary framework distribution.

public final class PixelFluxEngine {
  public static let shared: PixelFluxEngine
  public func applyBrightness(to inputImage: UIImage, brightness: Float) throws -> UIImage?
  public func applyPassthrough(to inputImage: UIImage) throws -> UIImage?
}

Properties

shared

A singleton instance of PixelFluxEngine. Use this for convenient filter application.

Methods

applyBrightness(to:brightness:)

Apply brightness adjustment to an image using a single call.

inputImage UIImage The source image.

brightness Float Brightness adjustment value (-1.0 to 1.0).

Returns: A new UIImage with brightness applied, or nil on error.

Throws: PixelFluxError if filter creation or application fails.

applyPassthrough(to:)

Apply passthrough (identity) filter to verify GPU pipeline.

inputImage UIImage The source image.

Returns: The input image after GPU processing, or nil on error.

Throws: PixelFluxError if filter application fails.

Example

let image = UIImage(named: "photo")!

// Using shared API
do {
  let brightened = try PixelFluxEngine.shared.applyBrightness(to: image, brightness: 0.2)
  imageView.image = brightened
} catch {
  print("Error:", error.localizedDescription)
}

Error Handling

PixelFluxError

Enumeration of errors that may be thrown by PixelFlux operations.

public enum PixelFluxError: LocalizedError {
  case noCGImage
  case metalLibraryNotFound
  case functionNotFound
  case commandBufferFailed
  case bufferCreationFailed
}

Cases

Error Case	Description	Common Causes
`noCGImage`	Input UIImage has no CGImage backing	Empty image, corrupted image data, or unsupported format
`metalLibraryNotFound`	Metal shader library (.metallib) not found	Framework linking issue, missing build phase
`functionNotFound`	Requested Metal compute function not in library	Incorrect function name, compilation error in shader
`commandBufferFailed`	Failed to create Metal command buffer	GPU context initialization failed, Metal unavailable
`bufferCreationFailed`	Failed to allocate GPU buffer for parameters	Out of VRAM, invalid buffer size

Error Handling Example

do {
  let filter = try BrightnessFilter(brightness: 0.5)
  let result = try filter.apply(to: image)
  imageView.image = result
} catch let error as PixelFluxError {
  switch error {
  case .noCGImage:
    print("Image is invalid or corrupted")
  case .metalLibraryNotFound:
    print("Metal shaders not properly linked")
  case .functionNotFound:
    print("Filter function not found in shader library")
  case .commandBufferFailed:
    print("GPU context unavailable")
  case .bufferCreationFailed:
    print("Failed to allocate GPU memory")
  }
} catch {
  print("Unknown error:", error)
}

Type Aliases

Metal Types

PixelFlux uses the following Metal types which are re-exported from the Metal framework:

MTLTexture - GPU-resident image data
MTLDevice - Represents the GPU
MTLCommandQueue - Queue for GPU commands
MTLCommandBuffer - Container for GPU command encoding
MTLComputeCommandEncoder - Encodes compute shader commands
MTLBuffer - GPU-resident memory buffer

Threading Model

All PixelFlux operations are synchronous and performed on the calling thread. The underlying GPU operations may be asynchronous, but apply() methods wait for GPU completion before returning.

Thread-Safe: PixelFlux filter instances are thread-safe and can be used from multiple threads concurrently
GPU Synchronization: Filter application blocks until GPU processing is complete
Background Processing: For UI responsiveness, dispatch filter operations to a background queue

Background Processing Example

DispatchQueue.global(qos: .userInitiated).async {
  do {
    let filter = try BrightnessFilter(brightness: 0.3)
    let result = try filter.apply(to: originalImage)

    DispatchQueue.main.async {
      self.imageView.image = result
    }
  } catch {
    print("Error:", error)
  }
}

Legacy API

In addition to the convenience apply(to:) methods, filters also implement the Filter protocol directly:

Direct Protocol Usage

let filter = try BrightnessFilter(brightness: 0.5)

// Convert UIImage to Metal texture
let texture = try makeTexture(from: image)

// Process at the Metal level
let outputTexture = try filter.process(texture)

// Convert back to UIImage
let result = textureToUIImage(outputTexture)