Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/wysaid/android-gpuimage-plus

Android Image & Camera Filters Based on OpenGL.
https://github.com/wysaid/android-gpuimage-plus
android-gpuimage cge filter opengl
Last synced: about 1 month ago
JSON representation
Android Image & Camera Filters Based on OpenGL.
Host: GitHub
URL: https://github.com/wysaid/android-gpuimage-plus
Owner: wysaid
License: mit
Created: 2015-11-20T07:47:36.000Z (almost 9 years ago)
Default Branch: master
Last Pushed: 2024-09-13T02:53:28.000Z (2 months ago)
Last Synced: 2024-10-02T01:22:12.153Z (about 2 months ago)
Topics: android-gpuimage, cge, filter, opengl
Language: C
Homepage:
Size: 114 MB
Stars: 1,808
Watchers: 96
Forks: 474
Open Issues: 324
Metadata Files:
- Readme: README.md
- Changelog: CHANGE.md
- License: LICENSE
Awesome Lists containing this project

README

        # Android-GPUImage-Plus

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

## New Feature

See the `image deform demo`.

![screenshots](screenshots/6.gif) ![screenshots](screenshots/5.gif)

## Gradle dependency

```gradle

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: 

## Build

* Options to know in `local.properties`:

  * `usingCMakeCompile=true`: Compile the native library with CMake if set to true. (Default to false, so you can use the prebuilt libs)

  * `usingCMakeCompileDebug=true`: Compile the native library in Debug Mode if set to true. (Default to false)

  * `disableVideoModule=true`: Disable the video recording feature(Useful for image only scenarios). The whole jni module size will be very small. (Default 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)](https://learn.microsoft.com/en-us/windows/wsl/install)__/__[MinGW](https://osdn.net/projects/mingw/)__/__[Cygwin](https://www.cygwin.com/)__ 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)](https://learn.microsoft.com/en-us/windows/wsl/install)__/__[MinGW](https://osdn.net/projects/mingw/)__/__[Cygwin](https://www.cygwin.com/)__ on Windows.)

  ```shell

  # 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)

  ```shell

  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 \library\src\main\jni

  \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](https://github.com/wysaid/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](https://github.com/wysaid/ios-gpuimage-plus "http://wysaid.org")

## Manual

### 1. Usage

___Sample Code for doing a filter with Bitmap___

```java

//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](https://github.com/wysaid/android-gpuimage-plus/blob/master/library/src/main/jni/include/cgeImageFilter.h#L42) or its child class. Most of the filters are inherited from [CGEImageFilterInterface](https://github.com/wysaid/android-gpuimage-plus/blob/master/library/src/main/jni/include/cgeImageFilter.h#L57) because it has many useful functions.

```cpp

// 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](https://github.com/wysaid/android-gpuimage-plus/blob/master/library/src/main/jni/source/customFilter_N.cpp).

#### 2.2 Run your own filter

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

```cpp

//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](https://github.com/wysaid/android-gpuimage-plus/blob/master/library/src/main/jni/interface/cgeSharedGLContext.h#L22) may be helpful.

__In Java, you can simply follow the sample:__

See: [CGENativeLibrary.cgeFilterImageWithCustomFilter](https://github.com/wysaid/android-gpuimage-plus/blob/master/cgeDemo/src/main/java/org/wysaid/cgeDemo/TestCaseActivity.java#L123)

__Or to do with a [CGEImageHandler](https://github.com/wysaid/android-gpuimage-plus/blob/master/library/src/main/java/org/wysaid/nativePort/CGEImageHandler.java#L93)__

### 3. Filter Rule String ###

Doc: 

En: [https://github.com/wysaid/android-gpuimage-plus/wiki/Parsing-String-Rule-(EN)](https://github.com/wysaid/android-gpuimage-plus/wiki/Parsing-String-Rule-(EN) "http://wysaid.org")

Ch: [https://github.com/wysaid/android-gpuimage-plus/wiki/Parsing-String-Rule-(ZH)](https://github.com/wysaid/android-gpuimage-plus/wiki/Parsing-String-Rule-(ZH) "http://wysaid.org")

## Tool

Some utils are available for creating filters: [https://github.com/wysaid/cge-tools](https://github.com/wysaid/cge-tools "http://wysaid.org")

[![Tool](https://raw.githubusercontent.com/wysaid/cge-tools/master/screenshots/0.jpg "cge-tool")](https://github.com/wysaid/cge-tools)

## License

[MIT License](https://github.com/wysaid/android-gpuimage-plus/blob/master/LICENSE)

## Donate

Alipay:

![Alipay](https://raw.githubusercontent.com/wysaid/android-gpuimage-plus/master/screenshots/alipay.jpg "alipay")

Paypal:

[![Paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif "Paypal")](http://blog.wysaid.org/p/donate.html)