GPUPixel: a C++ OpenGL filter engine for beauty effects on iOS and Android

What GPUPixel actually is, and who ends up using it

The README describes GPUPixel as a cross-platform image and video filter library written in C++11 on top of OpenGL/ES. The stated platform list is iOS, Android, Mac, Windows and Linux, with the caveat that it works on any OpenGL/ES platform. The advertised effects are beauty filters, and the repository topics name face detection and landmarks alongside thinface, which tells you the intended pipeline is camera frames in, face landmarks detected, geometry and colour adjusted, frames out.

The audience is narrow and specific. If you are building a native camera app, a live streaming client, or a video editor and you want the beauty and filter layer to be C++ rather than platform Swift or Kotlin, this is the shape of library you would look for. The topics list includes webrtc, which suggests the maintainers see real-time video calls as a target use. The README also thanks a sponsor, Facebetter, described as a face beauty effects SDK, so there is a commercial product adjacent to this open source core. That is worth knowing before you assume the project's roadmap is driven purely by outside contributors.

What it is not: there is no server component, no REST API, and no managed service. Everything runs in the client process against a GPU context you supply.

How the GPU pipeline is put together

The repository layout is the clearest evidence of the architecture. There is src/, include/, third_party/, cmake/, script/, demo/ and docs/. The split between include/ and src/ is the conventional C++ public-header versus implementation arrangement, so you link against the library and include headers rather than copying source into your app. The third_party/ directory means some dependencies are vendored rather than fetched at configure time, which reduces network dependency during a build but also means you inherit whatever versions were pinned at the last commit.

The engine is built on OpenGL/ES, so the data flow is the familiar one for this class of library: frames arrive as textures, a chain of shaders processes them, and the result is rendered to a surface or read back. GPUImage is listed first under Reference Projects, and GPUPixel's stated design follows that lineage, so anyone who has used GPUImage will recognise the filter-chain model. The topics mention face-detection and landmarks, which implies a detection step feeding parameters into the shader chain rather than a purely per-pixel colour filter. The demo directory has separate trees for android, desktop and ios, and demo/CMakeLists.txt exists at the demo level, so the desktop demo is CMake-driven while the mobile demos follow their own platform build systems.

Building GPUPixel on Linux with the provided Dockerfile

The README does not contain install or build commands. It points to gpupixel.pixpark.net for Introduction, Build, Demo and Integration guides. The repository does ship a Dockerfile at the top level, and its own comments give the build and run commands, so that is the most concrete starting point available without leaving the repository.

The Dockerfile is based on debian:bullseye and installs the X11, GLU, freeglut and Mesa development packages, then installs a newer CMake from the Kitware apt repository. It sets WORKDIR to /workspace, copies the project in, and its default command runs the Linux build script.

FROM debian:bullseye
WORKDIR /workspace
COPY . .
CMD ["/bin/bash", "-c", "./script/build_linux.sh"]

The comments at the bottom of the Dockerfile give the two commands to build the image and run it, with the output and build directories bind-mounted so artefacts survive the container.

docker build -t gpupixel .
docker run -it --rm -v $(pwd)/output:/workspace/output -v $(pwd)/build:/workspace/build gpupixel

After the run completes, look in the local output/ and build/ directories for the compiled library and the Linux demo. If the build fails, the first thing to check is whether the script and CMake files expect a different directory layout than the one the Dockerfile creates, since the README does not document the script's arguments. For iOS and Android, the README defers to the documentation site and to demo/ios and demo/android, and there are no commands in the repository for those targets.

Where GPUPixel will disappoint you

The largest gap is documentation inside the repository. The README's Getting Started section is four links, and the Build, Demo and Integration pages live on an external site. If that site is unreachable, or if the version documented there has drifted from main, you are reading CMakeLists.txt and the demo projects to work out how to wire the library in. That is a real cost for a library whose value proposition is saving you shader work.

Second, the platform matrix is wide but the toolchains are not uniform. iOS and Android demos each carry their own build system, and the desktop demo is CMake. A fix that works on Linux does not automatically translate to an Android NDK build. The Dockerfile targets Linux only.

Third, OpenGL/ES is the constraint. The README says the library is compatible with any OpenGL/ES platform, which is accurate but also means it does not target Metal, Vulkan or WebGPU. On Apple platforms you are running through the OpenGL compatibility path, and on Android you depend on the device's GLES driver. If your rendering stack is already Metal or Vulkan, adding an OpenGL/ES library means a second graphics context and the associated texture sharing work.

Finally, the release history shows a gap. v1.3.1 was published on 2025-06-27, and the next listed release is v1.2.x.8 on 2026-01-23, whose version number sorts below v1.3.1. That ordering is odd and the release notes are not published in the repository, so treat the version numbering as something to confirm against the tags before you pin a dependency. The last push to main was on 2026-08-29, so the repository is not dormant, but the release cadence and the branch activity do not obviously line up.

GPUPixel against GPUImage

The README lists GPUImage first among Reference Projects, and the two solve the same problem in the same way: a chain of GPU shaders applied to image or video frames, with the chain assembled in C++ or Objective-C. The difference in approach is what sits on top. GPUImage's original implementation is Objective-C for iOS and macOS, and the ecosystem around it is Apple-centric. GPUPixel is C++11 with OpenGL/ES, and the platform badge in the README explicitly lists iOS, Android, Mac, Windows and Linux. If you need one filter implementation shared across an Android app and an iOS app, that is the distinction that matters.

The second reference, GPUImage-x, is a cross-platform port of the same idea, and CainCamera is an Android beauty camera. GPUPixel's contribution relative to those is the packaging: a CMake build, a Dockerfile, a documentation site, and a demo tree covering ios, android and desktop. Whether that packaging is genuinely more convenient than the alternatives is something you can only judge by running the build on your own toolchain, which is exactly what the demos are for.

Licence and what upgrading costs you

GPUPixel is released under Apache-2.0, and the LICENSE file is at the repository root. Apache-2.0 is a permissive licence with an explicit patent grant, and it permits commercial and closed-source use provided you keep the licence and notice files and state significant changes. This is not legal advice; if you are shipping in a regulated or heavily audited product, have counsel review the notice obligations, including what the vendored code under third_party/ carries, since dependencies in that directory may have their own licences that the root LICENSE does not cover.

Upgrade cost is hard to estimate from the repository alone. There is a CHANGELOG.md at the top level, so release-to-release changes are tracked somewhere, but the README does not document a migration path between versions, and the release list does not include notes. The practical approach is to pin a tag, read CHANGELOG.md before moving, and rebuild the demo for each platform you ship. Because the library is C++ with a public include/ tree, an ABI change between releases will force a recompile of your app rather than a drop-in library swap.

Editorial conclusion

GPUPixel fits teams shipping a native mobile or desktop app that already has a camera or video pipeline and wants beauty and filter effects without writing GLSL from scratch. It is a poor fit if you need a maintained, self-contained build recipe inside the repository, or if your stack is web or Flutter, since the library is C++11 and OpenGL/ES. Before committing, verify the build guide at gpupixel.pixpark.net against your target platform, confirm the demo under demo/ios or demo/android matches your toolchain, and check whether the filter set you need exists in src/ rather than assuming the effect list in the README is complete.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. pixpark/gpupixel on GitHub
3. Project website
4. README
5. Releases