android-gpuimage-plus

Android-GPUImage-Plus

A C++ & Java library for Image/Camera/Video filters. PRs are welcomed.

New Features

v3.x adds CameraX support (CameraXProvider) and a unified zoom API (ICameraProvider.setZoomRatio).

Gradle dependency

…

Important: The 3.1.2-16k variants were linked with LLD 17 and can fail to load on 4KB-page-size devices with can't enable GNU RELRO protection ... Out of memory. Use 3.2.0 or newer; its 16KB variants are compatible with both 4KB and 16KB devices.

To compile other versions of ffmpeg, see: https://github.com/wysaid/FFmpeg-Android.git

Build

Quick start with Android Studio:

1. Add usingCMakeCompile=true to local.properties
2. Open the project in Android Studio
3. Wait for NDK/CMake initialization
4. Build and run

For detailed build instructions, configuration options, and alternative build methods (VS Code, command line, ndk-build), see docs/build.md.

Precompiled libraries: android-gpuimage-plus-libs
iOS version: ios-gpuimage-plus

Manual

1. Usage

Apply a filter with a rule string:

Bitmap srcImage = ...;

// HSL Adjust (hue: 0.02, saturation: -0.31, luminance: -0.17)
String ruleString = "@adjust hsl 0.02 -0.31 -0.17";

Bitmap dstImage = CGENativeLibrary.filterImage_MultipleEffects(srcImage, ruleString, 1.0f);

// Save result
ImageUtil.saveBitmap(dstImage);

2. Custom Shader Filter

2.1 Writing a Filter

Custom filters inherit from CGEImageFilterInterface:

…

See customFilter_N.cpp for a complete example.

2.2 Running a Custom Filter

In C++:

// Assumes GL context exists
CGEImageHandlerAndroid handler;
auto* customFilter = new MyCustomFilter();

customFilter->init();
handler.initWithBitmap(env, bitmap);
handler.addImageFilter(customFilter);  // Handler takes ownership

handler.processingFilters();
jobject resultBitmap = handler.getResultBitmap(env);

If no GL context exists, use CGESharedGLContext.

In Java:

Use CGENativeLibrary.cgeFilterImageWithCustomFilter or CGEImageHandler directly.

3. Filter Rule Strings

Filter effects are defined by text-based rule strings. See docs/filter-rules.md for complete syntax reference.

Quick example:

// Chain multiple filters with @ separator
String filter = "@curve RGB (0,0) (128,150) (255,255) " +
                "@adjust hsl 0.02 -0.31 -0.17 " +
                "@blend overlay texture.jpg 80";

4. Key Classes & Threading

Important: GL operations must run on the GL thread:

glSurfaceView.queueEvent(() -> {
    // Your GL operations here
});

Documentation

• docs/build.md — Full build guide and configuration options
• docs/filter-rules.md — Complete filter syntax reference
• .github/CONTRIBUTING.md — Contributing guidelines
• .github/RELEASE.md — Release process

Tool

CGE-Tools — open-source desktop companion for creating and previewing CGE filter rules (macOS / Linux / Windows). Latest release: v2.0.0.

Contributors

This project is built with help from the open-source community. Contributions of code, documentation, tests, bug reports, and reviews are all welcome.

License

MIT License