Android-GPUImage-Plus

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

New Feature

See the image deform demo.

Gradle dependency

allprojects {
    repositories {
        maven {
            // Use github hosted maven repo for now.
            // Will be uploaded to maven central later.
            url 'https://maven.wysaid.org/'
        }
    }
}

//Choose only one of them
dependencies {
    //All arch: armeabi-v7a, arm64-v8a, x86, x86_64 with video module (ffmpeg bundled)
    implementation 'org.wysaid:gpuimage-plus:3.0.0'

    //All arch: armeabi-v7a, arm64-v8a, x86, x86_64 without video module (no ffmpeg)
    implementation 'org.wysaid:gpuimage-plus:3.0.0-min'
}

The jcenter is out of date, please try the source for now. Latest prebuilt versions will be provided soon.

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

Build

• Important options in local.properties:

  • usingCMakeCompile=true: Set to true to compile the native library with CMake. Defaults to false, allowing the use of prebuilt libraries.
  • usingCMakeCompileDebug=true: Set to true to compile the native library in Debug Mode. Defaults to false.
  • disableVideoModule=true: Set to true to disable the video recording feature, which is useful for image-only scenarios. This reduces the size of the native library significantly. Defaults to false.
  • enable16kPageSizes=true: Set to true to enable 16k page sizes for the native library, applicable only in CMake compile mode. Defaults to false.

• Build with Android Studio and CMake: (Recommended)

  • Put usingCMakeCompile=true in your local.properties
  • Open the repo with the latest version of Android Studio
  • Waiting for the initialization. (NDK/cmake install)
  • Done.

• Using Visual Studio Code: (Requires WSL(Recommended)/MinGW/Cygwin on Windows.)

  • Setup ENV variable ANDROID_HOME to your Android SDK installation directory.
  • Open the repo with Visual Studio Code
  • Press ⌘ + shift + B (Mac) or ctrl + shift + B (Win/Linux), choose the option Enable CMake And Build Project With CMake.
  • Done.

• Build with preset tasks: (Requires WSL(Recommended)/MinGW/Cygwin on Windows.)

  # define the environment variable "ANDROID_HOME"
  # If using Windows, define ANDROID_HOME in Windows Environment Settings by yourself.
  export ANDROID_HOME=/path/to/android/sdk
  
  # Setup Project
  bash tasks.sh --setup-project
  
  # Compile with CMake Debug
  bash tasks.sh --debug --enable-cmake --build
  # Compile with CMake Release
  bash tasks.sh --release --enable-cmake --build
  
  # Start Demo By Command
  bash tasks.sh --run

• Build JNI part with ndk-build: (Not recommended)

  export NDK=path/of/your/ndk
  cd folder/of/jni (android-gpuimage-plus/library/src/main/jni)
  
  #This will make all arch: armeabi, armeabi-v7a arm64-v8a, x86, mips
  ./buildJNI
  #Or use "sh buildJNI"
  
  #Try this if you failed to run the shell above
  export CGE_USE_VIDEO_MODULE=1
  $NDK/ndk-build
  
  #If you don't want anything except the image filter,
  #Do as below to build with only cge module
  #No ffmpeg, opencv or faceTracker.
  #And remove the loading part of ffmpeg&facetracker
  $NDK/ndk-build
  
  #For Windows user, you should include the `.cmd` extension to `ndk-build` like this:
  cd <your\path\to\this\repo>\library\src\main\jni
  <your\path\to\ndk>\ndk-build.cmd
  
  #Also remember to comment out these line in NativeLibraryLoader
  //System.loadLibrary("ffmpeg");
  //CGEFFmpegNativeLibrary.avRegisterAll();

You can find precompiled libs here: android-gpuimage-plus-libs (The precompiled '.so' files are generated with NDK-r23b)

Note that the generated file "libFaceTracker.so" is not necessary. So just remove this file if you don't want any feature of it.

• iOS version: https://github.com/wysaid/ios-gpuimage-plus

Manual

1. Usage

Sample Code for doing a filter with Bitmap

//Simply apply a filter to a Bitmap.
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    Bitmap srcImage = ...;

    //HSL Adjust (hue: 0.02, saturation: -0.31, luminance: -0.17)
    //Please see the manual for more details.
    String ruleString = "@adjust hsl 0.02 -0.31 -0.17";

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

    //Then the dstImage is applied with the filter.

    //Save the result image to /sdcard/libCGE/rec_???.jpg.
    ImageUtil.saveBitmap(dstImage);
}

2. Custom Shader Filter

2.1 Write your own filter

Your filter must inherit CGEImageFilterInterfaceAbstract or its child class. Most of the filters are inherited from CGEImageFilterInterface because it has many useful functions.

// A simple customized filter to do a color reversal.
class MyCustomFilter : public CGE::CGEImageFilterInterface
{
public:
    
    bool init()
    {
        CGEConstString fragmentShaderString = CGE_SHADER_STRING_PRECISION_H
        (
        varying vec2 textureCoordinate;  //defined in 'g_vshDefaultWithoutTexCoord'
        uniform sampler2D inputImageTexture; // the same to above.

        void main()
        {
            vec4 src = texture2D(inputImageTexture, textureCoordinate);
            src.rgb = 1.0 - src.rgb;  //Simply reverse all channels.
            gl_FragColor = src;
        }
        );

        //m_program is defined in 'CGEImageFilterInterface'
        return m_program.initWithShaderStrings(g_vshDefaultWithoutTexCoord, s_fsh);
    }

    //void render2Texture(CGE::CGEImageHandlerInterface* handler, GLuint srcTexture, GLuint vertexBufferID)
    //{
    //  //Your own render functions here.
    //  //Do not override this function to use the CGEImageFilterInterface's.
    //}
};

Note: To add your own shader filter with c++. Please see the demo for further details.

2.2 Run your own filter

In C++, you can use a CGEImageHandler to do that:

//Assume the gl context already exists:
//JNIEnv* env = ...;
//jobject bitmap = ...;
CGEImageHandlerAndroid handler;
CustomFilterType* customFilter = new CustomFilterType();

//You should handle the return value (false is returned when failed.)
customFilter->init();
handler.initWithBitmap(env, bitmap);

//The customFilter will be released when the handler' destructor is called.
//So you don't have to call 'delete customFilter' if you add it into the handler.
handler.addImageFilter(customFilter);

handler.processingFilters(); //Run the filters.

jobject resultBitmap = handler.getResultBitmap(env);

If no gl context exists, the class CGESharedGLContext may be helpful.

In Java, you can simply follow the sample:

See: CGENativeLibrary.cgeFilterImageWithCustomFilter

Or to do with a CGEImageHandler

3. Filter Rule String

Doc: https://github.com/wysaid/android-gpuimage-plus/wiki

En: https://github.com/wysaid/android-gpuimage-plus/wiki/Parsing-String-Rule-(EN)

Ch: https://github.com/wysaid/android-gpuimage-plus/wiki/Parsing-String-Rule-(ZH)

Tool

Some utils are available for creating filters: https://github.com/wysaid/cge-tools

License

MIT License

Donate

Alipay:

Paypal: