Skip to content

Commit 688e436

Browse files
wysaidwysaid
committed
docs: restructure documentation and optimize README
- Consolidate usage.md into README Manual section - Add C++ custom filter examples and threading guidelines - Extract filter rules to docs/filter-rules.md (437 lines) - Reduce README from 254 to 193 lines (-24%) - Add Key Classes table and GL threading warnings - Move contributing/release docs to .github/ - Create AI instruction files (.github/skills/, copilot-instructions.md) - Add .copilotignore to exclude build artifacts BREAKING: docs/usage.md removed (content merged into README)
1 parent 7957985 commit 688e436

File tree

12 files changed

+1418
-261
lines changed

12 files changed

+1418
-261
lines changed

‎.copilotignore‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Build outputs
2+
build/
3+
.gradle/
4+
.cxx/
5+
*.apk
6+
*.aab
7+
8+
# Prebuilt native libraries (large binaries)
9+
library/src/main/libs/
10+
library/src/main/jni/ffmpeg/
11+
library/src/main/jni/ffmpeg-16kb/
12+
13+
# IDE configuration
14+
.idea/
15+
*.iml
16+
local.properties
17+
18+
# OS artifacts
19+
.DS_Store
20+
Thumbs.db
21+
22+
# Release artifacts
23+
demoRelease/

‎.github/CONTRIBUTING.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Contributing Guide
2+
3+
## Getting Started
4+
5+
1. Fork the repository
6+
2. Create a feature branch from `master` (`feat/xxx`, `fix/xxx`, `refactor/xxx`)
7+
3. Make your changes
8+
4. Verify the build: `bash tasks.sh --enable-cmake --build`
9+
5. Submit a pull request to `master`
10+
11+
## Code Standards
12+
13+
- Use **English** for all code comments, commit messages, and PR descriptions
14+
- Follow conventional-commit format for commits: `feat:`, `fix:`, `refactor:`, `chore:`
15+
- One logical change per commit
16+
17+
### C++ (Native)
18+
19+
- Follow `.clang-format` (Allman braces, 4-space indent)
20+
- All code in `namespace CGE {}`
21+
- No C++ exceptions (compiled with `-fno-exceptions`)
22+
- Use logging macros: `CGE_LOG_INFO`, `CGE_LOG_ERROR`, `CGE_LOG_KEEP`
23+
- Inline GLSL via `CGE_SHADER_STRING_PRECISION_H()` / `CGE_SHADER_STRING_PRECISION_M()`
24+
- Release GL resources (programs, textures, FBOs) along the handler lifecycle
25+
26+
### Java (Android)
27+
28+
- GL operations in `GLSurfaceView` subclasses must use `queueEvent(...)`
29+
- Load native libraries through `NativeLibraryLoader` only
30+
- Check `BuildConfig.CGE_USE_VIDEO_MODULE` before referencing FFmpeg classes
31+
32+
### JNI Bridge
33+
34+
- JNI function names: `Java_org_wysaid_nativePort_<Class>_<method>`
35+
- Always validate JNI parameters (null checks) before dereferencing
36+
- Never store JNI local references across calls
37+
38+
## Compatibility Rules
39+
40+
- **Do not change** method signatures in `org.wysaid.nativePort.*`
41+
- **Do not change** existing JNI function names
42+
- **Do not change** existing filter rule string syntax
43+
- New methods, filters, and syntax additions are welcome
44+
45+
## FFmpeg / Video Module
46+
47+
All FFmpeg-dependent code must be optional:
48+
49+
- C++: guard with `#ifdef CGE_USE_VIDEO_MODULE`
50+
- Java: check `BuildConfig.CGE_USE_VIDEO_MODULE`
51+
- Verify the project compiles with `--disable-video-module`
52+
53+
## Dual Build System
54+
55+
When adding new native source files under `library/src/main/jni/`:
56+
57+
- **CMake**: auto-discovered via `GLOB_RECURSE` — usually no action needed
58+
- **ndk-build**: update `Android.mk` to explicitly list the new files
59+
60+
## CI
61+
62+
Pull requests trigger CI on three platforms (macOS, Ubuntu, Windows). PRs run a reduced matrix (1 combination per platform); merges to `master` run the full 16-combination matrix.
63+
64+
Ensure all CI checks pass before requesting review.

‎.github/RELEASE.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Release Process
2+
3+
This project uses an automated release workflow triggered by version tags.
4+
5+
## Creating a Release
6+
7+
### 1. Update the Version
8+
9+
Edit `versionName` in `build.gradle`:
10+
11+
```gradle
12+
ext {
13+
android = [
14+
...
15+
versionName: "3.1.1",
16+
...
17+
]
18+
}
19+
```
20+
21+
### 2. Commit and Push
22+
23+
```bash
24+
git add build.gradle
25+
git commit -m "chore: bump version to 3.1.1"
26+
git push
27+
```
28+
29+
### 3. Tag and Push
30+
31+
```bash
32+
git tag v3.1.1
33+
git push origin v3.1.1
34+
```
35+
36+
## Automated Workflow
37+
38+
When a tag matching `v*.*.*` is pushed, the [release workflow](../.github/workflows/release.yml) will:
39+
40+
1. **Validate** that the tag version matches `versionName` in `build.gradle`
41+
2. **Build** four AAR variants:
42+
- `gpuimage-plus-{version}.aar` — Full with FFmpeg, 4KB page size
43+
- `gpuimage-plus-{version}-16k.aar` — Full with FFmpeg, 16KB page size
44+
- `gpuimage-plus-{version}-min.aar` — Image-only, 4KB page size
45+
- `gpuimage-plus-{version}-16k-min.aar` — Image-only, 16KB page size
46+
3. **Build** the demo APK (with video module)
47+
4. **Create** a GitHub release with all artifacts and release notes
48+
49+
## Tag Format
50+
51+
- Official: `v3.1.1`
52+
- Beta: `v3.1.1-beta1`
53+
- Alpha: `v3.1.1-alpha1`
54+
- Release candidate: `v3.1.1-rc1`
55+
56+
All version parts must be pure numbers. The tag version must exactly match `versionName` in `build.gradle`.

‎.github/copilot-instructions.md‎

Lines changed: 34 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,52 @@
11
# GitHub Copilot Instructions — android-gpuimage-plus
22

3-
This repo is a widely-used Android GPU filter library. Prefer **small, safe, backward-compatible** changes.
3+
Android GPU filter library (C++ & Java). Prefer **small, safe, backward-compatible** changes.
44

5-
## Non‑negotiables (stability first)
5+
## Stability Rules
66

7-
- **Do not break compatibility**: avoid changing public Java APIs, JNI method signatures, or filter rule string syntax.
8-
- Prefer **additive** changes (new classes/methods/filters) over refactors.
9-
- Keep FFmpeg/video code **fully optional** (both Java and native side guards).
7+
- **Never break public API**: `org.wysaid.nativePort.*` Java signatures, JNI method names, and filter rule string syntax are stable contracts.
8+
- Prefer **additive** changes over refactoring existing code.
9+
- FFmpeg/video code must remain **fully optional** — guard with `disableVideoModule` (Java/Gradle) / `CGE_USE_VIDEO_MODULE` (C++).
1010

11-
## Where things live (only what’s non-obvious)
11+
## Project Layout
1212

13-
- Java public API / JNI front door: `library/src/main/java/org/wysaid/nativePort/`
14-
- `CGENativeLibrary`, `CGEImageHandler`, `CGEFrameRenderer`, `CGEFrameRecorder`
15-
- Native engine: `library/src/main/jni/cge/`
16-
- JNI bridge (Java ↔ C++): `library/src/main/jni/interface/`
17-
- Extension filters (built as `libCGEExt.so`): `library/src/main/jni/custom/`
18-
- Prebuilt FFmpeg variants: `library/src/main/jni/ffmpeg/` and `ffmpeg-16kb/`
19-
- Demo app (`cgeDemo/`) is for examples; avoid coupling new library APIs to demo-only code.
13+
| Path | Purpose |
14+
|------|---------|
15+
| `library/src/main/java/org/wysaid/nativePort/` | Public Java API (`CGENativeLibrary`, `CGEImageHandler`, etc.) |
16+
| `library/src/main/jni/cge/` | Core C++ engine |
17+
| `library/src/main/jni/interface/` | JNI bridge (Java ↔ C++) |
18+
| `library/src/main/jni/custom/` | Extension filters (`libCGEExt.so`) |
19+
| `library/src/main/jni/ffmpeg/`, `ffmpeg-16kb/` | Prebuilt FFmpeg variants |
20+
| `cgeDemo/` | Demo app — don't couple library APIs to demo-only code |
2021

21-
## Build toggles you must respect
22+
## Build
2223

23-
These flags come from `local.properties` (see `settings.gradle`):
24+
Use `tasks.sh` for all operations (`bash tasks.sh --help`). Key `local.properties` flags: `usingCMakeCompile`, `disableVideoModule`, `enable16kPageSizes`. See `docs/build.md` for details.
2425

25-
- `usingCMakeCompile`: build native code via CMake; otherwise use prebuilt `.so` in `library/src/main/libs/`.
26-
- `usingCMakeCompileDebug`: toggles Debug vs Release native build.
27-
- `disableVideoModule`: when true, **no FFmpeg / no recording**.
28-
- `enable16kPageSizes`: enables 16KB page-size linking flags and uses `ffmpeg-16kb`.
29-
- `deployArtifacts`: enables maven publishing tasks.
26+
**Important**: CMake uses `GLOB_RECURSE`; ndk-build (`Android.mk`) lists sources **explicitly** — update both when adding native files.
3027

31-
Important: CMake uses recursive globs, but **ndk-build (`Android.mk`) lists sources explicitly**. If you add native files that must compile in ndk-build mode, update `Android.mk` accordingly.
28+
## Code Conventions
3229

33-
## Native/C++ conventions that matter here
30+
Language-specific rules live in `.github/instructions/` and are auto-applied by file path — see `cpp.instructions.md`, `java.instructions.md`, `jni-bridge.instructions.md`.
3431

35-
- Follow `.clang-format` (Allman braces, 4 spaces, no tabs). Keep code in `namespace CGE {}`.
36-
- **No C++ exceptions** (compiled with `-fno-exceptions`). Use return values and log errors.
37-
- Use project logging macros: `CGE_LOG_INFO`, `CGE_LOG_KEEP`, `CGE_LOG_ERROR`.
38-
- Inline shader strings via `CGE_SHADER_STRING_PRECISION_H()` / `CGE_SHADER_STRING_PRECISION_M()`.
32+
For detailed standards, see `.github/CONTRIBUTING.md`.
3933

40-
## Java/OpenGL thread rules (project-specific pitfalls)
34+
## Documentation
4135

42-
- For `GLSurfaceView`-based classes, do GL operations on the GL thread via `queueEvent(...)`.
43-
- `NativeLibraryLoader` controls native library loading order; don’t unconditionally load FFmpeg when video module is disabled.
36+
- `docs/build.md` — Full build guide and configuration options
37+
- `docs/usage.md` — API usage, custom filters, and code samples
38+
- `.github/RELEASE.md` — Release process and versioning
39+
- `.github/CONTRIBUTING.md` — Contributing guidelines and code standards
4440

45-
## Adding a new GPU filter / feature (minimal checklist)
41+
## Skills
4642

47-
1. Implement the filter in `library/src/main/jni/custom/` (or `cge/filters/` if it’s core).
48-
2. Initialize shaders/uniforms in `init()`; handle compile/link failures without crashing.
49-
3. Ensure GL resources are released (programs/textures/FBOs) along the existing lifecycle.
50-
4. If the feature is exposed to Java, add/update JNI wrappers under `library/src/main/jni/interface/` and keep signatures stable.
51-
5. If it should be reachable from rule strings, update the parsing/registration in the native engine (don’t change existing syntax).
52-
6. Keep FFmpeg/video-dependent logic behind `disableVideoModule` / `CGE_USE_VIDEO_MODULE` guards.
43+
- **Submit PR:** Follow `.github/skills/pr-submit/SKILL.md` to create or update pull requests
44+
- **Review PR:** Follow `.github/skills/pr-review/SKILL.md` to review pull requests
5345

54-
## Communication & docs
46+
## Behavior Constraints
5547

56-
- Use **English** for code comments, commit messages, and PR descriptions.
57-
- Don’t add new “how to build” tutorials here—put long-form docs in `README.md` (this file should stay short).
48+
- **Validation:** After native code changes, ALWAYS run `bash tasks.sh --enable-cmake --build`.
49+
- **Commit Policy:** Only commit to feature branches, never force-push to `master`.
50+
- **Completeness:** Implement fully or request clarification — no TODOs in committed code.
51+
- **Dual Build:** When adding native files, update both `CMakeLists.txt` and `Android.mk`.
52+
- **Thread Safety:** Never call OpenGL ES functions outside the GL thread.

‎.github/instructions/cpp.instructions.md‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
11
---
22
description: "Use when editing C++ native code. Covers CGE engine conventions, shader patterns, memory safety, and OpenGL ES resource management."
3-
applyTo:
4-
- "library/src/main/jni/cge/**/*.{cpp,h,c}"
5-
- "library/src/main/jni/custom/**/*.{cpp,h,c}"
6-
- "library/src/main/jni/interface/**/*.{cpp,h,c}"
3+
applyTo: "library/src/main/jni/{cge,custom,interface}/**/*.{cpp,h,c}"
74
---
85

96
# C++ / Native Layer

‎.github/instructions/java.instructions.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
---
22
description: "Use when editing Java Android library or demo code. Covers GL thread safety and native interop patterns."
3-
applyTo:
4-
- "library/src/main/java/**/*.java"
5-
- "cgeDemo/src/main/java/**/*.java"
3+
applyTo: "library/src/main/java/**/*.java|cgeDemo/src/main/java/**/*.java"
64
---
75

86
# Java / Android Layer

‎.github/skills/pr-review/SKILL.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
name: pr-review
3+
description: Review a GitHub Pull Request for API stability, build compliance, native code safety, and code quality
4+
---
5+
6+
## When to Use
7+
8+
- Need to review a pull request before merge
9+
- Validate PR changes against project rules
10+
- Provide structured review feedback
11+
12+
## Constraints
13+
14+
- All review comments **must** be in English
15+
- Work through checks **in order** — stop and flag any blocker immediately
16+
- Reference `.github/CONTRIBUTING.md` for detailed code standards
17+
18+
## Procedure
19+
20+
Follow `.github/CONTRIBUTING.md` for detailed rules. Check in order:
21+
22+
1. **API Stability** (Blocker):
23+
- No changes to `org.wysaid.nativePort.*` method signatures
24+
- No changes to JNI function names
25+
- Filter rule string syntax backward-compatible
26+
2. **Build Toggle Compliance** (Blocker):
27+
- FFmpeg/video code properly guarded (C++: `#ifdef CGE_USE_VIDEO_MODULE`, Java: `BuildConfig.CGE_USE_VIDEO_MODULE`)
28+
- Compiles with `disableVideoModule=true`
29+
3. **Native Code Safety** (High):
30+
- No C++ exceptions, JNI null checks, GL resource cleanup, shader error handling
31+
4. **Dual Build System** (Medium):
32+
- New native files → `Android.mk` updated
33+
5. **Code Quality**: Follow CONTRIBUTING.md standards
34+
6. **CI Status**: All platform workflows pass
35+
36+
## Output
37+
38+
Structure the review as:
39+
40+
```markdown
41+
## PR Review: <PR title>
42+
43+
### Summary
44+
One-sentence assessment: Approve / Request Changes / Needs Discussion
45+
46+
### Findings
47+
48+
#### Blockers
49+
- (API stability or build toggle violations)
50+
51+
#### Issues
52+
- (correctness, safety, or quality problems)
53+
54+
#### Suggestions
55+
- (optional improvements, not blocking)
56+
57+
### Verdict
58+
APPROVE / REQUEST_CHANGES with rationale
59+
```
60+
61+
## Severity Guide
62+
63+
| Severity | Criteria | Action |
64+
|----------|----------|--------|
65+
| **Blocker** | API break, build toggle violation, crash bug | Request changes |
66+
| **Issue** | Memory/GL resource leak, missing null check, wrong thread | Request changes if risky, else comment |
67+
| **Suggestion** | Style, naming, minor optimization | Comment only |

‎.github/skills/pr-submit/SKILL.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
name: pr-submit
3+
description: Create or update a GitHub Pull Request after completing code changes
4+
---
5+
6+
## When to Use
7+
8+
- Code changes are complete and ready for review
9+
- Need to create a new PR or update an existing one
10+
11+
## Constraints
12+
13+
- PR title, description, and comments **must** be in English
14+
- Follow conventional-commit format for titles: `feat:`, `fix:`, `refactor:`, `chore:`
15+
- Target branch: `master`
16+
- **Never** force-push to `master`
17+
- Follow `.github/CONTRIBUTING.md` for code standards and compatibility rules
18+
19+
## Procedure
20+
21+
1. **Verify Build**: Run `bash tasks.sh --enable-cmake --build`
22+
- If touching FFmpeg/video code: verify with `--disable-video-module`
23+
- If new native files added: confirm `Android.mk` updated
24+
2. **Check Compatibility**: Review `.github/CONTRIBUTING.md` compatibility rules
25+
- Confirm no public API signature changes in `org.wysaid.nativePort.*`
26+
3. **Branch & Commit**:
27+
- Create feature branch if on `master` (`feat/`, `fix/`, `refactor/`)
28+
- Follow conventional-commit format (see CONTRIBUTING.md)
29+
4. **Create PR**: Push branch and create PR against `master`
30+
- Use conventional-commit format for title
31+
- Fill in description template below
32+
5. **Verify CI**: Ensure all platform workflows pass
33+
34+
## PR Description Template
35+
36+
```markdown
37+
## Summary
38+
39+
Brief description of what this PR does and why.
40+
41+
## Changes
42+
43+
- Bullet list of key changes
44+
45+
## Compatibility
46+
47+
- [ ] No public API changes (`org.wysaid.nativePort.*`)
48+
- [ ] No filter rule string syntax changes
49+
- [ ] FFmpeg/video code guarded with `disableVideoModule` / `CGE_USE_VIDEO_MODULE` (or N/A)
50+
- [ ] Both CMake and ndk-build updated (or N/A — no new native source files)
51+
52+
## Testing
53+
54+
How was this tested (e.g., "built with CMake + no-ffmpeg on macOS", "ran cgeDemo on Pixel 7").
55+
```
56+
57+
## Output
58+
59+
- PR with English title and description
60+
- All CI checks passing

0 commit comments

Comments
 (0)