If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/BradLarson/GPUImage2 shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 17 active contributors
• BSD-3-Clause licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 79% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live BradLarson/GPUImage2 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/BradLarson/GPUImage2.

What it runs against: a local clone of BradLarson/GPUImage2 — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in BradLarson/GPUImage2 | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 844 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of BradLarson/GPUImage2. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/BradLarson/GPUImage2.git
#   cd GPUImage2
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of BradLarson/GPUImage2 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "BradLarson/GPUImage2(\\.git)?\\b" \\
  && ok "origin remote is BradLarson/GPUImage2" \\
  || miss "origin remote is not BradLarson/GPUImage2 (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 844 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~814d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/BradLarson/GPUImage2"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

GPUImage 2 is a Swift framework for real-time GPU-accelerated image and video processing on Mac, iOS, and Linux using OpenGL (ES) shaders. It lets developers build complex image manipulation pipelines by chaining filters (vertex and fragment shaders) to process camera feeds, video files, and still images at 60+ FPS on mobile and 20+ FPS on embedded devices like Raspberry Pi. Monorepo structure: core framework code likely in Sources/, platform-specific examples in examples/{Mac,Linux-OpenGL,Linux-RPi}/, with each example being a standalone Swift Package (Package.swift files). Processing pipeline architecture: image sources → filter chains (built from smaller operations) → outputs (screen, file, raw data, movie).

iOS and macOS app developers building real-time video processing features (live camera filters, effects), machine vision pipelines, and embedded Linux developers on devices like Raspberry Pi who need GPU-accelerated image processing without managing raw OpenGL state.

Actively maintained but past peak usage. The repo shows solid engineering (BSD license, comprehensive examples across Mac/iOS/Linux, 598K lines of production Swift), but lacks visible recent commits, CI/CD setup, or test suite in the file list. Production-ready for common filter chains, but community activity appears moderate.

Single-maintainer project (Brad Larson controls the canonical repo), no visible test infrastructure in file list, and Swift 3 requirement is now significantly outdated (Swift is at v5.9+). Dependency on LodePNG and SwiftGD adds external maintenance burden. Video4Linux dependency on Linux could break with newer kernel changes.

Not explicitly visible from file list alone, but examples for Mac (FilterShowcase with multiple filters), Linux (ImageFilterNotebook.ipynb, OpenGL variants), and RPi (SimpleVideoFilter with compile.sh) suggest ongoing maintenance across platforms. No PR/issue data provided, so check GitHub directly for recent activity.

git clone https://github.com/BradLarson/GPUImage2.git
cd GPUImage2
swift build
# Or open examples/Mac/FilterShowcase/FilterShowcase.xcodeproj in Xcode

Daily commands: For Mac examples: open examples/Mac/FilterShowcase/FilterShowcase.xcodeproj && ⌘R in Xcode. For Linux: cd examples/Linux-OpenGL/SimpleImageFilter && swift build && swift run. For Raspberry Pi: cd examples/Linux-RPi/SimpleVideoFilter && bash compile.sh.

• Package.swift: SPM manifest defining dependencies, Swift version requirement, and how framework is packaged across platforms.
• examples/Mac/FilterShowcase/FilterShowcase/FilterOperations.swift: Reference implementation of 20+ real filters (blur, edge detect, color shifts) showing how to wrap GLSL shaders into reusable Swift operations.
• examples/Mac/FilterShowcase/FilterShowcase/FilterOperationTypes.swift: Enumerates all available filter types; critical reference for what filters exist and how they're organized.
• examples/Linux-OpenGL/SimpleImageFilter/Sources/main.swift: Minimal end-to-end example of loading an image, applying a filter, and saving output on Linux—good onboarding starting point.
• examples/Mac/SimpleVideoFilter/SimpleVideoFilter/AppDelegate.swift: Shows real-time video input pipeline setup: camera → filter chain → screen output on macOS.
• License.txt: BSD license + declarations of LodePNG (zlib) and SwiftGD (MIT) dependencies and compliance requirements.

For new filters: study examples/Mac/FilterShowcase/FilterOperations.swift (defines filter types) and FilterOperations.swift (implements them). Add GLSL shaders in the framework's shader directory (not visible in file list—check Sources/). For platform support: look at examples/{Mac,Linux-OpenGL,Linux-RPi} as templates. For core pipeline logic: locate the input/output chain classes in the main Swift source (not shown in top 60).

Swift 3 is EOL; upgrading to modern Swift may require significant syntax and API changes. Video4Linux (V4L2) on Linux requires system packages installed (apt-get install libv4l-dev on Ubuntu) or camera won't initialize. Xcode examples may not open on newer Xcode versions (Swift 3 syntax). GPU memory exhaustion possible with 4K video on mobile without explicit texture pooling (not evident in file list). No visible test suite means filter behavior changes require manual verification.

• GPU Shader Pipeline (Vertex & Fragment Shaders) — GPUImage 2's entire processing model revolves around GLSL vertex/fragment shaders running on GPU; understanding the fixed-function pipeline and how shaders transform pixels in parallel is essential to adding custom filters.
• Framebuffer Objects (FBO) & Render-to-Texture — The framework chains filters by rendering output of one shader into a texture that becomes input to the next; without understanding FBO ping-ponging and texture bindings, debugging filter chains is impossible.
• Real-Time Video Capture & AVFoundation Integration — On iOS/macOS, GPUImage 2 integrates with AVFoundation camera APIs; understanding frame delegation and CMSampleBuffer handling is critical for live video input pipelines.
• Processing Pipeline (Observer Pattern) — GPUImage 2 uses a source→filter→output chain where each stage notifies downstream subscribers of new frames; this is the architectural backbone for composing complex filters.
• Texture Formats & Memory Layout (RGBA, YUV) — Video frames come in different color spaces (RGB, YUV420 on camera input); shaders must sample correctly or colors will be wrong. GPUImage 2 abstracts this but misunderstanding causes subtle bugs.
• Cross-Platform Abstraction (OpenGL vs OpenGL ES vs Metal) — GPUImage 2 targets Mac (OpenGL), iOS (OpenGL ES), and Linux (OpenGL); shader syntax and API differ subtly; understanding platform-specific #defines in GLSL is essential.
• Video4Linux (V4L2) Camera Interface — On Linux, camera input relies on V4L2 syscalls; understanding device enumeration, format negotiation, and frame polling is needed to debug or extend Raspberry Pi camera support.

• BradLarson/GPUImage — The original Objective-C implementation (GPUImage 1); historical reference for algorithm and filter design before Swift rewrite.
• apple/swift-coreimage-filters — Apple's native CoreImage framework (alternative on iOS/macOS); GPUImage 2 is lighter-weight and cross-platform but less integrated with OS.
• Harley-xk/PixelTest — Swift image testing library; useful for writing golden-image tests for GPUImage 2 filters to catch regressions.
• SwiftGL/SwiftGL — Low-level Swift bindings to OpenGL; GPUImage 2 likely wraps or uses similar abstractions for cross-platform shader compilation.
• nicklockwood/GLView — Lightweight OpenGL view for iOS; complements GPUImage 2 for custom rendering needs when full filter pipeline is overkill.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Linux-specific CI workflow with GitHub Actions for OpenGL examples

The repo has Linux-OpenGL and Linux-RPi example directories but no automated CI testing. A new contributor could add a GitHub Actions workflow that builds and tests the Linux examples (SimpleImageFilter, SimpleVideoFilter) on each push. This ensures Linux support doesn't regress and validates the Package.swift manifests work correctly.

• [ ] Create .github/workflows/linux-ci.yml that installs Swift and OpenGL dependencies
• [ ] Add build step for examples/Linux-OpenGL/SimpleImageFilter/Package.swift
• [ ] Add build step for examples/Linux-OpenGL/SimpleVideoFilter/Package.swift
• [ ] Test on ubuntu-latest runner with libgl1-mesa-dev and other OpenGL headers
• [ ] Document Linux build requirements in README.md

Create unit tests for core GPU filter pipeline with XCTest

The repo structure shows multiple example apps (Mac/iOS/Linux) but there's no visible test directory or XCTest suite for the core GPUImage2 framework itself. A contributor should add comprehensive unit tests covering filter chaining, image input/output, and video processing basics to ensure framework stability across platforms.

• [ ] Create Tests/ directory at repo root with GPUImage2Tests target
• [ ] Add XCTest cases for basic filter operations (color adjustment, blur, etc)
• [ ] Add tests for PictureInput and VideoInput pipeline construction
• [ ] Add tests for filter chain serialization and output validation
• [ ] Integrate test target into Package.swift and ensure it runs in CI

Consolidate Mac example projects into a single multi-target Xcode workspace

Currently there are 5 separate Mac example Xcode projects (FilterShowcase, SimpleImageFilter, SimpleMovieFilter, SimpleVideoFilter, SimpleVideoRecorder) scattered across examples/Mac/, each with its own .xcodeproj and Info.plist. This creates maintenance overhead. A contributor could refactor these into a single workspace with multiple targets, share common build settings, and reduce duplication in the examples/SharedAssets directory.

• [ ] Create examples/Mac/GPUImageExamples.xcworkspace
• [ ] Convert each example into a target within one consolidated project structure
• [ ] Move shared AppIcon assets to a common location referenced by all targets
• [ ] Consolidate duplicated Info.plist settings into a shared configuration
• [ ] Update README.md to explain the new workspace structure and how to build individual examples

• Add unit tests for the image processing pipeline: create Tests/ directory with XCTest cases for each filter in FilterOperations.swift to verify output against golden image files.
• Port FilterShowcase example to Swift 5+ syntax and update Package.swift to drop Swift 3 requirement, then test across macOS 10.14+ and iOS 12+.
• Document the filter chain architecture with a walkthrough example in README.md showing how to build a custom three-filter pipeline (e.g., blur → grayscale → edge detect) from scratch.

The GPUImage2 repository demonstrates a generally secure baseline. The codebase appears to be a GPU processing framework without typical injection vectors (no SQL, web APIs, or data serialization from untrusted sources based on available file listing). However, minor issues exist: HTTP URLs in documentation should be upgraded to HTTPS, and a formal security vulnerability disclosure process should be established. The inability to fully analyze dependencies due to missing Package.swift contents prevents a higher security score. No hardcoded secrets, exposed credentials, or Docker/infrastructure misconfigurations were identified in the provided file structure.

• Low · Missing HTTPS in README Image URL — README.md. The README.md file references an image from 'http://sunsetlakesoftware.com' using unencrypted HTTP protocol. This could expose users to man-in-the-middle attacks or cache poisoning if accessing documentation. Fix: Change the image URL to use HTTPS: https://sunsetlakesoftware.com/sites/default/files/GPUImageLogo.png
• Low · Incomplete Dependency Analysis - Package.swift Not Examined — Package.swift. The Package.swift file structure is present but its contents were not provided for analysis. This file typically contains dependency declarations, and without reviewing it, transitive dependency vulnerabilities cannot be fully assessed. Fix: Provide the full contents of Package.swift for dependency vulnerability scanning. Use tools like 'swift package update --dry-run' and check against known vulnerability databases.
• Low · No Security Policy or Vulnerability Disclosure Process — Repository root. No SECURITY.md, security policy, or vulnerability disclosure guidelines are present in the repository. This makes it difficult for security researchers to responsibly report vulnerabilities. Fix: Add a SECURITY.md file documenting how users should report security vulnerabilities (e.g., contact@sunsetlakesoftware.com or security@example.com instead of public issues).

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.