From 7f103226d2381a2b1123328a80a4505cf9dfe91f Mon Sep 17 00:00:00 2001
From: Littlegnal <8847263+littleGnAl@users.noreply.github.com>
Date: Wed, 3 Apr 2024 00:42:59 +0800
Subject: [PATCH] Add more documentation for shared native handle feature
 (#1668)

---
 README.md                                     |  9 +++++
 .../process_video_raw_data.dart               | 33 ++++++++++++++++++-
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 963321efc..da3bfe4c2 100644
--- a/README.md
+++ b/README.md
@@ -106,6 +106,15 @@ You can directly depend on the Agora CDN for testing purposes:
 </html>
 ```
 
+### Interact with Agora RTC Native SDK(Android/iOS only)
+> **NOTE**: This feature requires `agora_rtc_engine` >= 6.3.0
+
+Due to performance constraints, direct implementation of advanced features like video and audio raw data processing is not currently feasible in Flutter side.
+
+We enable you to create an `RtcEngine` within Flutter by utilizing the native handle from the `RtcEngine`(Android) or `AgoraRtcEngineKit`(iOS) of the Agora RTC Native SDK. This approach enables your application to directly utilize the advanced features of the Agora RTC Native SDK through the `agora_rtc_engine` package, bridging the gap between native capabilities and Flutter's environment.
+
+More detail, please check the [ProcessVideoRawData](example/lib/examples/advanced/process_video_raw_data/process_video_raw_data.dart) example for reference.
+
 ## API Reference Resources
 
 * [Flutter](https://api-ref.agora.io/en/voice-sdk/flutter/6.x/API/rtc_api_overview_ng.html)
diff --git a/example/lib/examples/advanced/process_video_raw_data/process_video_raw_data.dart b/example/lib/examples/advanced/process_video_raw_data/process_video_raw_data.dart
index e67fd0ec6..400908764 100644
--- a/example/lib/examples/advanced/process_video_raw_data/process_video_raw_data.dart
+++ b/example/lib/examples/advanced/process_video_raw_data/process_video_raw_data.dart
@@ -7,6 +7,25 @@ import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 
 /// ProcessVideoRawData Example
+/// 
+/// This example demonstrates how to create a `RtcEngine` (Android)/`AgoraRtcEngineKit` (iOS)
+/// and share the native handle with the Flutter side. By doing so, the `agora_rtc_engine` 
+/// acts as a proxy, allowing you to invoke the functions of the `RtcEngine` (Android)/`AgoraRtcEngineKit` (iOS).
+/// 
+/// The key point of how to use it:
+/// * Initializes the `RtcEngine` (Android)/`AgoraRtcEngineKit` (iOS) on the native side.
+/// * Retrieves the native handle through the `RtcEngine.getNativeHandle`(Android)/`AgoraRtcEngineKit.getNativeHandle`(iOS) 
+///   function on the native side, and passes it to the Flutter side through the Flutter `MethodChannel`.
+/// * Passes the native handle to the `createAgoraRtcEngine`(Flutter) on the Flutter side, 
+///   then the `RtcEngine`(Flutter) can call the functions through the shared native handle.
+/// 
+/// This example creates a `RtcEngine` (Android)/`AgoraRtcEngineKit` (iOS) on the native side
+/// and registers the video frame observer to modify the video raw data. It makes the local 
+/// preview appear in gray for demonstration purposes.
+/// 
+/// The native side implementation can be found at:
+/// - Android: `example/android/app/src/main/kotlin/io/agora/agora_rtc_flutter_example/VideoRawDataController.kt`
+/// - iOS: `example/ios/Runner/VideoRawDataController.m`
 class ProcessVideoRawData extends StatefulWidget {
   /// Construct the [ProcessVideoRawData]
   const ProcessVideoRawData({Key? key}) : super(key: key);
@@ -46,15 +65,27 @@ class _State extends State<ProcessVideoRawData> {
   Future<void> _dispose() async {
     await _engine.leaveChannel();
     await _engine.release();
+    // Destroys the `RtcEngine`(Android)/`AgoraRtcEngineKit`(iOS) on native side.
+    // Note that this should be called after the Flutter side `RtcEngine.release` function.
+    //
+    // See native side implementation:
+    // Android: `example/android/app/src/main/kotlin/io/agora/agora_rtc_flutter_example/MainActivity.kt`
+    // iOS: `example/ios/Runner/AppDelegate.m`
     await _sharedNativeHandleChannel.invokeMethod('native_dispose');
   }
 
   Future<void> _initEngine() async {
+    // Initializes the `RtcEngine`(Android)/`AgoraRtcEngineKit`(iOS) on native side, 
+    // and retrieves the native handle of `RtcEngine`(Android)/`AgoraRtcEngineKit`(iOS).
+    //
+    // See native side implementation:
+    // Android: `example/android/app/src/main/kotlin/io/agora/agora_rtc_flutter_example/MainActivity.kt`
+    // iOS: `example/ios/Runner/AppDelegate.m`
     final sharedNativeHandle = await _sharedNativeHandleChannel.invokeMethod(
       'native_init',
       {'appId': config.appId},
     );
-
+    // Passes the native handle from `RtcEngine`(Android)/`AgoraRtcEngineKit`(iOS) on native side.
     _engine = createAgoraRtcEngine(sharedNativeHandle: sharedNativeHandle);
     await _engine.initialize(RtcEngineContext(
       appId: config.appId,