Skip to content

Commit 1f91710

Browse files
camsim99camsim99
authored
[camerax] Update README with plugin overview (flutter#3891)
Updates the README of the `camera_android_camerax` plugin with an overview and instructions as to how to use the plugin. Also adds `CONTRIBUTING.md` for further information on how to contribute to the plugin.
1 parent d71e5c6 commit 1f91710

File tree

3 files changed

+143
-2
lines changed

3 files changed

+143
-2
lines changed

‎packages/camera/camera_android_camerax/CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,4 @@
2121
* Implements image streaming.
2222
* Provides LifecycleOwner implementation for Activities that use the plugin that do not implement it themselves.
2323
* Implements retrieval of camera information.
24+
* Updates README.md with plugin overview and adds contribution guide to CONTRIBUTING.md.

‎packages/camera/camera_android_camerax/CONTRIBUTING.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Contributing to camera\_android\_camerax
2+
3+
## Plugin structure
4+
5+
The `camera_platform_interface` implementation is located at
6+
`lib/src/android_camera_camerax.dart`, and it is implemented using Dart classes
7+
that are wrapped versions of native Android Java classes.
8+
9+
In this approach, each native Android library used in the plugin implementation
10+
is represented by an equivalent Dart class. Instances of these classes are
11+
considered paired and represent each other in Java and Dart, respectively. An
12+
`InstanceManager`, which is essentially a map between `long` identifiers and
13+
objects that also provides notifications when an object has become unreachable
14+
by memory. There is both a Dart and Java `InstanceManager` implementation, so
15+
when a Dart instance is created that represens an Android native instance,
16+
both are stored in the `InstanceManager` of their respective language with a
17+
shared `long` identifier. These `InstanceManager`s take callbacks that run
18+
when objects become unrechable or removed, allowing the Dart library to easily
19+
handle removing references to native resources automatically. To ensure all
20+
created instances are properly managed and to more easily allow for testing,
21+
each wrapped Android native class in Dart takes an `InstanceManager` and has
22+
a detached constructor, a constructor that allows for the creation of instances
23+
not attached to the `InstanceManager` and unlinked to a paired Android native
24+
instance.
25+
26+
In `lib/src/`, you will find all of the Dart-wrapped native Android classes that
27+
the plugin currently uses in its implementation. As aforementioned, each of
28+
these classes uses an `InstanceManager` (implementation in `instance_manager.dart`)
29+
to manage objects that are created by the plugin implementation that map to objects
30+
of the same type created in the native Android code. This plugin uses [`pigeon`][1]
31+
to generate the communication layer between Flutter and native Android code, so each
32+
of these Dart-wrapped classes may also have Host API and Flutter API implementations
33+
that handle communication to the host native Android platform and from the host
34+
native Android platform, respectively. The communication interface is defined in
35+
the `pigeons/camerax_library.dart` file. After editing the communication interface,
36+
regenerate the communication layer by running
37+
`dart run pigeon --input pigeons/camerax_library.dart` from the plugin root.
38+
39+
In the native Java Android code in `android/src/main/java/io/flutter/plugins/camerax/`,
40+
you'll find the Host API and Flutter API implementations of the same classes
41+
wrapped with Dart in `lib/src/` that handle communication from that Dart code
42+
and to that Dart code, respectively. The Host API implementations should directly
43+
delegate calls to the CameraX or other wrapped Android libraries and should not
44+
have any additional logic or abstraction; any exceptions should be thoroughly
45+
documented in the code. As aforementioned, the objects created in the native
46+
Android code map to objects created on the Dart side and are also managed by
47+
an `InstanceManager` (implementation in `InstanceManager.java`).
48+
49+
If CameraX or other Android classes that you need to access do not have a
50+
duplicately named implementation in `lib/src/`, then follow the same structure
51+
described above to add them.
52+
53+
For more information, please see the [design document][2] or feel free
54+
to ask any questions on the #hackers-ecosystem channel on [Discord][6]. For
55+
more information on contributing packages in general, check out our
56+
[contribution guide][3].
57+
58+
## Testing
59+
60+
While none of the generated `pigeon` files are tested, all plugin impelementation and
61+
wrapped native Android classes (Java & Dart) are tested. You can find the Java tests under
62+
`android/src/test/java/io/flutter/plugins/camerax/` and the Dart tests under `test/`. To
63+
run these tests, please see the instructions in the [running plugin tests guide][5].
64+
65+
Besides [`pigeon`][1], this plugin also uses [`mockito`][4] to generate mock objects for
66+
testing purposes. To generate the mock objects, run
67+
`dart run build_runner build --delete-conflicting-outputs`.
68+
69+
70+
[1]: https://pub.dev/packages/pigeon
71+
[2]: https://docs.google.com/document/d/1wXB1zNzYhd2SxCu1_BK3qmNWRhonTB6qdv4erdtBQqo/edit?usp=sharing&resourcekey=0-WOBqqOKiO9SARnziBg28pg
72+
[3]: https://github.com/flutter/packages/blob/main/CONTRIBUTING.md
73+
[4]: https://pub.dev/packages/mockito
74+
[5]: https://github.com/flutter/flutter/wiki/Plugin-Tests#running-tests
75+
[6]: https://github.com/flutter/flutter/wiki/Chat

‎packages/camera/camera_android_camerax/README.md

Lines changed: 67 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,68 @@
1-
# camera_android_camerax
1+
# camera\_android\_camerax
22

3-
An implementation of the camera plugin on Android using CameraX.
3+
An Android implementation of [`camera`][1] that uses the [CameraX library][2].
4+
5+
*Note*: This package is under development, so please note the
6+
[missing features and limitations](#missing-features-and-limitations), but
7+
otherwise feel free to try out the current implementation and provide any
8+
feedback by filing issues under [`flutter/flutter`][5] with `[camerax]` in
9+
the title, which will be actively triaged.
10+
11+
## Usage
12+
13+
This package is [non-endorsed][3]; the endorsed Android implementation of `camera`
14+
is [`camera_android`][4]. To use this implementation of the plugin instead of
15+
`camera_android`, you will need to specify it in your `pubsepc.yaml` file as a
16+
dependency in addition to `camera`:
17+
18+
```yaml
19+
dependencies:
20+
# ...along with your other dependencies
21+
camera: ^0.10.4
22+
camera_android_camerax: ^0.5.0
23+
```
24+
25+
## Missing features and limitations
26+
27+
### Resolution configuration \[[Issue #120462][120462]\]
28+
29+
Any specified `ResolutionPreset` wll go unused in favor of CameraX defaults and
30+
`onCameraResolutionChanged` is unimplemented.
31+
32+
### Locking/Unlocking capture orientation \[[Issue #125915][125915]\]
33+
34+
`lockCaptureOrientation` & `unLockCaptureOrientation` are unimplemented.
35+
36+
### Flash mode configuration \[[Issue #120715][120715]\]
37+
38+
`setFlashMode` is unimplemented.
39+
40+
### Exposure mode, point, & offset configuration \[[Issue #120468][120468]\]
41+
42+
`setExposureMode`, `setExposurePoint`, & `setExposureOffset` are unimplemented.
43+
44+
### Focus mode & point configuration \[[Issue #120467][120467]\]
45+
46+
`setFocusMode` & `setFocusPoint` are unimplemented.
47+
48+
### Zoom configuration \[[Issue #125371][125371]\]
49+
50+
`setZoomLevel` is unimplemented.
51+
52+
## Contributing
53+
54+
For more information on contributing to this plugin, see [`CONTRIBUTING.md`](CONTRIBUTING.md).
55+
56+
<!-- Links -->
57+
58+
[1]: https://pub.dev/packages/camera
59+
[2]: https://developer.android.com/training/camerax
60+
[3]: https://docs.flutter.dev/packages-and-plugins/developing-packages#non-endorsed-federated-plugin
61+
[4]: https://pub.dev/packages/camera_android
62+
[5]: https://github.com/flutter/flutter/issues/new/choose
63+
[120462]: https://github.com/flutter/flutter/issues/120462
64+
[125915]: https://github.com/flutter/flutter/issues/125915
65+
[120715]: https://github.com/flutter/flutter/issues/120715
66+
[120468]: https://github.com/flutter/flutter/issues/120468
67+
[120467]: https://github.com/flutter/flutter/issues/120467
68+
[125371]: https://github.com/flutter/flutter/issues/125371

0 commit comments

Comments
 (0)