diff --git a/packages/camera/camera_android_camerax/CHANGELOG.md b/packages/camera/camera_android_camerax/CHANGELOG.md index 1c901a82bfa..c80f0884f55 100644 --- a/packages/camera/camera_android_camerax/CHANGELOG.md +++ b/packages/camera/camera_android_camerax/CHANGELOG.md @@ -21,3 +21,4 @@ * Implements image streaming. * Provides LifecycleOwner implementation for Activities that use the plugin that do not implement it themselves. * Implements retrieval of camera information. +* Updates README.md with plugin overview and adds contribution guide to CONTRIBUTING.md. diff --git a/packages/camera/camera_android_camerax/CONTRIBUTING.md b/packages/camera/camera_android_camerax/CONTRIBUTING.md new file mode 100644 index 00000000000..3d365d791e5 --- /dev/null +++ b/packages/camera/camera_android_camerax/CONTRIBUTING.md @@ -0,0 +1,75 @@ +# Contributing to camera\_android\_camerax + +## Plugin structure + +The `camera_platform_interface` implementation is located at +`lib/src/android_camera_camerax.dart`, and it is implemented using Dart classes +that are wrapped versions of native Android Java classes. + +In this approach, each native Android library used in the plugin implementation +is represented by an equivalent Dart class. Instances of these classes are +considered paired and represent each other in Java and Dart, respectively. An +`InstanceManager`, which is essentially a map between `long` identifiers and +objects that also provides notifications when an object has become unreachable +by memory. There is both a Dart and Java `InstanceManager` implementation, so +when a Dart instance is created that represens an Android native instance, +both are stored in the `InstanceManager` of their respective language with a +shared `long` identifier. These `InstanceManager`s take callbacks that run +when objects become unrechable or removed, allowing the Dart library to easily +handle removing references to native resources automatically. To ensure all +created instances are properly managed and to more easily allow for testing, +each wrapped Android native class in Dart takes an `InstanceManager` and has +a detached constructor, a constructor that allows for the creation of instances +not attached to the `InstanceManager` and unlinked to a paired Android native +instance. + +In `lib/src/`, you will find all of the Dart-wrapped native Android classes that +the plugin currently uses in its implementation. As aforementioned, each of +these classes uses an `InstanceManager` (implementation in `instance_manager.dart`) +to manage objects that are created by the plugin implementation that map to objects +of the same type created in the native Android code. This plugin uses [`pigeon`][1] +to generate the communication layer between Flutter and native Android code, so each +of these Dart-wrapped classes may also have Host API and Flutter API implementations +that handle communication to the host native Android platform and from the host +native Android platform, respectively. The communication interface is defined in +the `pigeons/camerax_library.dart` file. After editing the communication interface, +regenerate the communication layer by running +`dart run pigeon --input pigeons/camerax_library.dart` from the plugin root. + +In the native Java Android code in `android/src/main/java/io/flutter/plugins/camerax/`, +you'll find the Host API and Flutter API implementations of the same classes +wrapped with Dart in `lib/src/` that handle communication from that Dart code +and to that Dart code, respectively. The Host API implementations should directly +delegate calls to the CameraX or other wrapped Android libraries and should not +have any additional logic or abstraction; any exceptions should be thoroughly +documented in the code. As aforementioned, the objects created in the native +Android code map to objects created on the Dart side and are also managed by +an `InstanceManager` (implementation in `InstanceManager.java`). + +If CameraX or other Android classes that you need to access do not have a +duplicately named implementation in `lib/src/`, then follow the same structure +described above to add them. + +For more information, please see the [design document][2] or feel free +to ask any questions on the #hackers-ecosystem channel on [Discord][6]. For +more information on contributing packages in general, check out our +[contribution guide][3]. + +## Testing + +While none of the generated `pigeon` files are tested, all plugin impelementation and +wrapped native Android classes (Java & Dart) are tested. You can find the Java tests under +`android/src/test/java/io/flutter/plugins/camerax/` and the Dart tests under `test/`. To +run these tests, please see the instructions in the [running plugin tests guide][5]. + +Besides [`pigeon`][1], this plugin also uses [`mockito`][4] to generate mock objects for +testing purposes. To generate the mock objects, run +`dart run build_runner build --delete-conflicting-outputs`. + + +[1]: https://pub.dev/packages/pigeon +[2]: https://docs.google.com/document/d/1wXB1zNzYhd2SxCu1_BK3qmNWRhonTB6qdv4erdtBQqo/edit?usp=sharing&resourcekey=0-WOBqqOKiO9SARnziBg28pg +[3]: https://github.com/flutter/packages/blob/main/CONTRIBUTING.md +[4]: https://pub.dev/packages/mockito +[5]: https://github.com/flutter/flutter/wiki/Plugin-Tests#running-tests +[6]: https://github.com/flutter/flutter/wiki/Chat \ No newline at end of file diff --git a/packages/camera/camera_android_camerax/README.md b/packages/camera/camera_android_camerax/README.md index 06d837ac721..a357008b8ba 100644 --- a/packages/camera/camera_android_camerax/README.md +++ b/packages/camera/camera_android_camerax/README.md @@ -1,3 +1,68 @@ -# camera_android_camerax +# camera\_android\_camerax -An implementation of the camera plugin on Android using CameraX. +An Android implementation of [`camera`][1] that uses the [CameraX library][2]. + +*Note*: This package is under development, so please note the +[missing features and limitations](#missing-features-and-limitations), but +otherwise feel free to try out the current implementation and provide any +feedback by filing issues under [`flutter/flutter`][5] with `[camerax]` in +the title, which will be actively triaged. + +## Usage + +This package is [non-endorsed][3]; the endorsed Android implementation of `camera` +is [`camera_android`][4]. To use this implementation of the plugin instead of +`camera_android`, you will need to specify it in your `pubsepc.yaml` file as a +dependency in addition to `camera`: + +```yaml +dependencies: + # ...along with your other dependencies + camera: ^0.10.4 + camera_android_camerax: ^0.5.0 +``` + +## Missing features and limitations + +### Resolution configuration \[[Issue #120462][120462]\] + +Any specified `ResolutionPreset` wll go unused in favor of CameraX defaults and +`onCameraResolutionChanged` is unimplemented. + +### Locking/Unlocking capture orientation \[[Issue #125915][125915]\] + +`lockCaptureOrientation` & `unLockCaptureOrientation` are unimplemented. + +### Flash mode configuration \[[Issue #120715][120715]\] + +`setFlashMode` is unimplemented. + +### Exposure mode, point, & offset configuration \[[Issue #120468][120468]\] + +`setExposureMode`, `setExposurePoint`, & `setExposureOffset` are unimplemented. + +### Focus mode & point configuration \[[Issue #120467][120467]\] + +`setFocusMode` & `setFocusPoint` are unimplemented. + +### Zoom configuration \[[Issue #125371][125371]\] + +`setZoomLevel` is unimplemented. + +## Contributing + +For more information on contributing to this plugin, see [`CONTRIBUTING.md`](CONTRIBUTING.md). + + + +[1]: https://pub.dev/packages/camera +[2]: https://developer.android.com/training/camerax +[3]: https://docs.flutter.dev/packages-and-plugins/developing-packages#non-endorsed-federated-plugin +[4]: https://pub.dev/packages/camera_android +[5]: https://github.com/flutter/flutter/issues/new/choose +[120462]: https://github.com/flutter/flutter/issues/120462 +[125915]: https://github.com/flutter/flutter/issues/125915 +[120715]: https://github.com/flutter/flutter/issues/120715 +[120468]: https://github.com/flutter/flutter/issues/120468 +[120467]: https://github.com/flutter/flutter/issues/120467 +[125371]: https://github.com/flutter/flutter/issues/125371 \ No newline at end of file