Skip to main content

camera_android/
lib.rs

1//! Android USB permission integration and JNI adapter. Camera2 capture in the
2//! core `camera` crate does not require this package or a Java context.
3#![warn(missing_docs)]
4#![warn(unsafe_op_in_unsafe_fn)]
5pub mod android;
6/// Stable Android adapter error types and JNI boundary payloads.
7pub mod error;
8mod owned_fd;
9use camera::{
10    BackendId, BackendPolicy, CameraSystem, CaptureRequest, ControlId, ControlMode, ControlValue,
11    Device, DeviceSelector, Frame, FrameRate, FrameReceiver, Session, SubscriptionOptions,
12};
13#[cfg(feature = "convert-rgb")]
14use camera::{ConversionRequest, PixelFormat, RgbConverter};
15use error::{CameraError, Result};
16use jni::{
17    objects::{JByteBuffer, JClass, JObject, JString},
18    sys::{jboolean, jint, jlong, jstring, JNI_FALSE, JNI_TRUE},
19    JNIEnv,
20};
21use serde_json::{json, Value};
22#[cfg(feature = "uvc")]
23use std::os::fd::AsFd;
24use std::{
25    collections::HashMap,
26    sync::{
27        atomic::{AtomicBool, AtomicI64, Ordering},
28        Arc, Mutex, OnceLock,
29    },
30    time::Duration,
31};
32
33#[derive(Clone, Debug)]
34/// Description of a USB video device discovered through Android's `UsbManager`.
35pub struct UsbDeviceInfo {
36    /// Stable index within the current scan result.
37    pub index: u32,
38    /// User-facing device name.
39    pub name: String,
40    /// Additional device description supplied by Android.
41    pub description: String,
42    /// USB vendor identifier, when Android exposes it.
43    pub vendor_id: Option<u16>,
44    /// USB product identifier, when Android exposes it.
45    pub product_id: Option<u16>,
46    /// USB serial number, when the application has permission to read it.
47    pub serial_number: Option<String>,
48    /// Android USB device path used by the permission and open calls.
49    pub device_path: Option<String>,
50}
51struct Reader {
52    session: Arc<Session>,
53    frames: FrameReceiver,
54    pending: Option<Frame>,
55    #[cfg(feature = "convert-rgb")]
56    converter: RgbConverter,
57    #[cfg(feature = "convert-rgb")]
58    rgb: Vec<u8>,
59}
60struct Handle {
61    closed: AtomicBool,
62    lifecycle: Mutex<()>,
63    camera: tokio::sync::Mutex<Device>,
64    session: Mutex<Option<Arc<Session>>>,
65    reader: tokio::sync::Mutex<Option<Reader>>,
66    native_output: AtomicBool,
67}
68static HANDLES: OnceLock<Mutex<HashMap<i64, Arc<Handle>>>> = OnceLock::new();
69static NEXT: AtomicI64 = AtomicI64::new(1);
70fn registry() -> &'static Mutex<HashMap<i64, Arc<Handle>>> {
71    HANDLES.get_or_init(|| Mutex::new(HashMap::new()))
72}
73fn runtime() -> &'static tokio::runtime::Runtime {
74    static RT: OnceLock<tokio::runtime::Runtime> = OnceLock::new();
75    RT.get_or_init(|| {
76        tokio::runtime::Builder::new_multi_thread()
77            .enable_all()
78            .build()
79            .expect("JNI camera runtime")
80    })
81}
82fn invalid(message: impl Into<String>) -> CameraError {
83    CameraError::adapter(camera::CameraErrorKind::InvalidState, message)
84}
85fn handle(id: i64) -> Result<Arc<Handle>> {
86    registry()
87        .lock()
88        .map_err(|_| invalid("Handle registry poisoned"))?
89        .get(&id)
90        .cloned()
91        .ok_or_else(|| invalid("Unknown camera handle"))
92}
93fn session(handle: &Handle) -> Result<Arc<Session>> {
94    handle
95        .session
96        .lock()
97        .map_err(|_| invalid("Session state poisoned"))?
98        .clone()
99        .ok_or_else(|| invalid("Camera is not streaming"))
100}
101fn store(camera: Device) -> Result<i64> {
102    let id = NEXT.fetch_add(1, Ordering::Relaxed);
103    if id <= 0 {
104        return Err(invalid("Handle space exhausted"));
105    }
106    registry()
107        .lock()
108        .map_err(|_| invalid("Handle registry poisoned"))?
109        .insert(
110            id,
111            Arc::new(Handle {
112                closed: AtomicBool::new(false),
113                lifecycle: Mutex::new(()),
114                camera: tokio::sync::Mutex::new(camera),
115                session: Mutex::new(None),
116                reader: tokio::sync::Mutex::new(None),
117                native_output: AtomicBool::new(true),
118            }),
119        );
120    Ok(id)
121}
122fn backend(name: &str) -> Result<Option<BackendId>> {
123    Ok(match name.to_ascii_lowercase().as_str() {
124        "camera2" => Some(BackendId::CAMERA2),
125        "uvc" => Some(BackendId::UVC),
126        "v4l2" => Some(BackendId::V4L2),
127        "auto" => None,
128        _ => return Err(invalid("Backend must be auto, camera2, uvc, or v4l2")),
129    })
130}
131
132fn capture_format(name: &str) -> Result<camera::CaptureFormat> {
133    use camera::CaptureFormat;
134    match name.trim().to_ascii_lowercase().as_str() {
135        "mjpeg" | "mjpg" => Ok(CaptureFormat::Mjpeg),
136        "yuyv" | "yuy2" => Ok(CaptureFormat::Yuyv),
137        "uyvy" => Ok(CaptureFormat::Uyvy),
138        "nv12" => Ok(CaptureFormat::Nv12),
139        "rgb" | "rgb8" => Ok(CaptureFormat::Rgb8),
140        "h264" => Ok(CaptureFormat::H264),
141        "gray" | "gray8" => Ok(CaptureFormat::Gray8),
142        _ => Err(invalid("Unknown capture format")),
143    }
144}
145
146fn frame_interval_payload(interval: camera::FrameInterval) -> Value {
147    json!({"numerator":interval.numerator,"denominator":interval.denominator})
148}
149
150fn capability_payload(capabilities: camera::DeviceCapabilities) -> Value {
151    let (knowledge, reason, modes) = match capabilities.capture_modes {
152        camera::CapabilityKnowledge::Known(modes) => ("known", None, modes),
153        camera::CapabilityKnowledge::Representative { values, reason } => {
154            ("representative", Some(reason), values)
155        }
156        camera::CapabilityKnowledge::Unknown { reason } => ("unknown", Some(reason), Vec::new()),
157    };
158    let modes = modes
159        .into_iter()
160        .map(|mode| {
161            json!({
162                "format":format!("{:?}",mode.format),
163                "width":mode.width,
164                "height":mode.height,
165                "frameRateNumerator":mode.frame_rate.numerator(),
166                "frameRateDenominator":mode.frame_rate.denominator(),
167                "framesPerSecond":mode.frame_rate.as_f64()
168            })
169        })
170        .collect::<Vec<_>>();
171    let ranges = capabilities
172        .capture_mode_ranges
173        .into_iter()
174        .map(|range| {
175            json!({
176                "format":format!("{:?}",range.format),
177                "kind":format!("{:?}",range.kind),
178                "width":{"min":range.width.minimum,"max":range.width.maximum,"step":range.width.step},
179                "height":{"min":range.height.minimum,"max":range.height.maximum,"step":range.height.step},
180                "frameIntervals":range.frame_intervals.into_iter().map(|interval|json!({
181                    "kind":format!("{:?}",interval.kind),
182                    "minimum":frame_interval_payload(interval.minimum),
183                    "maximum":frame_interval_payload(interval.maximum),
184                    "step":interval.step.map(frame_interval_payload),
185                    "atResolution":{"width":interval.at_resolution.0,"height":interval.at_resolution.1}
186                })).collect::<Vec<_>>()
187            })
188        })
189        .collect::<Vec<_>>();
190    let conversions = capabilities
191        .conversions
192        .into_iter()
193        .map(|conversion| {
194            json!({
195                "input":format!("{:?}",conversion.input),
196                "output":format!("{:?}",conversion.output),
197                "available":conversion.available,
198                "requirement":conversion.requirement
199            })
200        })
201        .collect::<Vec<_>>();
202    json!({
203        "knowledge":knowledge,
204        "reason":reason,
205        "modes":modes,
206        "ranges":ranges,
207        "nativeFormats":capabilities.native_formats.into_iter().map(|format|format!("{format:?}")).collect::<Vec<_>>(),
208        "conversions":conversions,
209        "limitations":capabilities.limitations
210    })
211}
212
213fn system_for(backend: Option<BackendId>) -> Result<CameraSystem> {
214    let policy = backend
215        .map(BackendPolicy::Require)
216        .unwrap_or(BackendPolicy::PlatformDefault);
217    Ok(CameraSystem::builder().backend_policy(policy).build()?)
218}
219
220#[cfg(feature = "uvc")]
221fn usb_devices() -> Result<Vec<Value>> {
222    Ok(android::usb_manager_scan()?
223        .into_iter()
224        .map(|d| json!({"id":d.device_path,"index":d.index,"name":d.name,"description":d.description,"vendorId":d.vendor_id,"productId":d.product_id}))
225        .collect())
226}
227#[cfg(not(feature = "uvc"))]
228fn usb_devices() -> Result<Vec<Value>> {
229    Err(camera::CameraError::backend_not_compiled(BackendId::UVC).into())
230}
231
232#[cfg(feature = "uvc")]
233fn open_usb_path(path: &str) -> Result<Device> {
234    let fd = android::usb_device_open(path)?;
235    Ok(runtime().block_on(system_for(Some(BackendId::UVC))?.open_usb_fd(fd.as_fd()))?)
236}
237#[cfg(not(feature = "uvc"))]
238fn open_usb_path(_path: &str) -> Result<Device> {
239    Err(camera::CameraError::backend_not_compiled(BackendId::UVC).into())
240}
241
242#[cfg(feature = "uvc")]
243fn open_usb_descriptor(fd: jint) -> Result<Device> {
244    let owned = owned_fd::duplicate(fd)?;
245    Ok(runtime().block_on(system_for(Some(BackendId::UVC))?.open_usb_fd(owned.as_fd()))?)
246}
247#[cfg(not(feature = "uvc"))]
248fn open_usb_descriptor(_fd: jint) -> Result<Device> {
249    Err(camera::CameraError::backend_not_compiled(BackendId::UVC).into())
250}
251fn boundary<T: Default>(
252    env: &mut JNIEnv<'_>,
253    operation: impl FnOnce(&mut JNIEnv<'_>) -> Result<T>,
254) -> T {
255    match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| operation(env))) {
256        Ok(Ok(value)) => value,
257        Ok(Err(error)) => {
258            let _ = env.throw_new(
259                "com/medivh/camera/CameraException",
260                error.boundary_payload(),
261            );
262            T::default()
263        }
264        Err(_) => {
265            let payload =
266                CameraError::adapter(camera::CameraErrorKind::Internal, "Camera adapter panicked")
267                    .boundary_payload();
268            let _ = env.throw_new("com/medivh/camera/CameraException", payload);
269            T::default()
270        }
271    }
272}
273fn output(env: &mut JNIEnv<'_>, value: Value) -> Result<jstring> {
274    Ok(env.new_string(value.to_string())?.into_raw())
275}
276fn text(env: &mut JNIEnv<'_>, value: JString<'_>) -> Result<String> {
277    Ok(env.get_string(&value)?.into())
278}
279
280#[no_mangle]
281/// JNI entry point that stores the application context used for USB access.
282pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeInitWithContext(
283    mut env: JNIEnv,
284    class: JClass,
285    context: JObject,
286) {
287    let _ = class;
288    boundary(&mut env, |env| {
289        let vm = env.get_java_vm()?;
290        let context = env.new_global_ref(context)?;
291        android::init_android_context(vm, context);
292        Ok(())
293    });
294}
295#[no_mangle]
296/// JNI entry point that enumerates devices for the requested backend.
297pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeDevices(
298    mut env: JNIEnv,
299    _class: JClass,
300    name: JString,
301) -> jstring {
302    boundary(&mut env, |env| {
303        let selected = backend(&text(env, name)?)?;
304        let devices = if selected.as_ref() == Some(&BackendId::UVC) {
305            usb_devices()?
306        } else {
307            runtime().block_on(system_for(selected)?.devices())?.into_iter().map(|d|json!({"id":d.id.native_id(),"persistentId":d.id.to_persistent_string(),"index":d.index,"name":d.name,"description":d.description,"facing":format!("{:?}",d.facing)})).collect()
308        };
309        output(env, json!(devices))
310    })
311}
312
313#[no_mangle]
314/// JNI entry point that returns the device capability matrix as JSON.
315pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeCapabilities(
316    mut env: JNIEnv,
317    _class: JClass,
318    name: JString,
319    id: JString,
320) -> jstring {
321    boundary(&mut env, |env| {
322        let selected = backend(&text(env, name)?)?;
323        let native_id = text(env, id)?;
324        let capabilities = if selected.as_ref() == Some(&BackendId::UVC) {
325            let camera = open_usb_path(&native_id)?;
326            runtime().block_on(camera.capabilities())?
327        } else {
328            let system = system_for(selected)?;
329            let device = runtime()
330                .block_on(system.devices())?
331                .into_iter()
332                .find(|device| device.id.native_id() == native_id)
333                .ok_or_else(|| camera::CameraError::device_not_found(native_id.clone()))?;
334            runtime().block_on(system.capabilities(&device.id))?
335        };
336        output(env, capability_payload(capabilities))
337    })
338}
339#[no_mangle]
340/// JNI entry point that reports whether a USB device path is authorized.
341pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeHasPermission(
342    mut env: JNIEnv,
343    _class: JClass,
344    path: JString,
345) -> jboolean {
346    boundary(&mut env, |env| {
347        Ok(if android::usb_device_has_permission(&text(env, path)?)? {
348            JNI_TRUE
349        } else {
350            JNI_FALSE
351        })
352    })
353}
354#[no_mangle]
355/// JNI entry point that starts Android's USB permission flow.
356pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeRequestPermission(
357    mut env: JNIEnv,
358    _class: JClass,
359    path: JString,
360) {
361    boundary(&mut env, |env| {
362        android::usb_device_request_permission(&text(env, path)?)
363    })
364}
365#[no_mangle]
366/// JNI entry point that opens a camera by backend name and native device ID.
367pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeOpen(
368    mut env: JNIEnv,
369    _class: JClass,
370    name: JString,
371    id: JString,
372) -> jlong {
373    boundary(&mut env, |env| {
374        let selected = backend(&text(env, name)?)?;
375        let id = text(env, id)?;
376        let camera = if selected.as_ref() == Some(&BackendId::UVC) {
377            open_usb_path(&id)?
378        } else {
379            let system = system_for(selected)?;
380            runtime().block_on(async {
381                let device = system
382                    .devices()
383                    .await?
384                    .into_iter()
385                    .find(|d| d.id.native_id() == id)
386                    .ok_or_else(|| camera::CameraError::device_not_found(id.clone()))?;
387                system.open(DeviceSelector::Id(device.id)).await
388            })?
389        };
390        store(camera)
391    })
392}
393#[no_mangle]
394/// JNI entry point that opens UVC capture from an authorized USB descriptor.
395pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeOpenUsbFd(
396    mut env: JNIEnv,
397    _class: JClass,
398    fd: jint,
399) -> jlong {
400    boundary(&mut env, |_| {
401        if fd < 0 {
402            return Err(invalid("Negative USB descriptor"));
403        }
404        store(open_usb_descriptor(fd)?)
405    })
406}
407
408fn start_handle(
409    id: jlong,
410    width: jint,
411    height: jint,
412    numerator: jint,
413    denominator: jint,
414    format: Option<camera::CaptureFormat>,
415    native_output: bool,
416) -> Result<Value> {
417    if width <= 0 || height <= 0 || numerator <= 0 || denominator <= 0 {
418        return Err(invalid("Dimensions and frame rate must be positive"));
419    }
420    #[cfg(not(feature = "convert-rgb"))]
421    if !native_output {
422        return Err(invalid(
423            "RGB delivery was requested but camera-android/convert-rgb is not enabled",
424        ));
425    }
426    let handle = handle(id)?;
427    let mut builder = CaptureRequest::builder()
428        .preferred_frame_rate(FrameRate::new(numerator as u32, denominator as u32)?);
429    if let Some(format) = format {
430        builder = builder
431            .exact_resolution(width as u32, height as u32)
432            .preferred_formats([format]);
433    } else {
434        builder = builder.preferred_resolution(width as u32, height as u32);
435    }
436    let request = builder.build()?;
437    let _gate = handle
438        .lifecycle
439        .lock()
440        .map_err(|_| invalid("Lifecycle state poisoned"))?;
441    if handle.closed.load(Ordering::Acquire) {
442        return Err(invalid("Camera is closed"));
443    }
444    let session = runtime().block_on(async {
445        let mut camera = handle.camera.lock().await;
446        camera.start(request).await
447    })?;
448    handle.native_output.store(native_output, Ordering::Release);
449    let config = session.negotiated();
450    let result = json!({"width":config.capture.width,"height":config.capture.height,"frameRateNumerator":config.capture.frame_rate.numerator(),"frameRateDenominator":config.capture.frame_rate.denominator(),"captureFormat":format!("{:?}",config.capture.format),"output":if native_output {"Native"} else {"Rgb8"},"adjustments":config.adjustments});
451    *handle
452        .session
453        .lock()
454        .map_err(|_| invalid("Session state poisoned"))? = Some(Arc::new(session));
455    Ok(result)
456}
457
458#[no_mangle]
459/// JNI entry point that starts capture using automatic format negotiation.
460pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeStart(
461    mut env: JNIEnv,
462    _class: JClass,
463    id: jlong,
464    width: jint,
465    height: jint,
466    numerator: jint,
467    denominator: jint,
468    native: jboolean,
469) -> jstring {
470    boundary(&mut env, |env| {
471        output(
472            env,
473            start_handle(
474                id,
475                width,
476                height,
477                numerator,
478                denominator,
479                None,
480                native == JNI_TRUE,
481            )?,
482        )
483    })
484}
485
486#[no_mangle]
487/// JNI entry point that starts capture with an explicitly requested format.
488pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeStartWithFormat(
489    mut env: JNIEnv,
490    _class: JClass,
491    id: jlong,
492    width: jint,
493    height: jint,
494    numerator: jint,
495    denominator: jint,
496    format: JString,
497    native: jboolean,
498) -> jstring {
499    boundary(&mut env, |env| {
500        let format = capture_format(&text(env, format)?)?;
501        output(
502            env,
503            start_handle(
504                id,
505                width,
506                height,
507                numerator,
508                denominator,
509                Some(format),
510                native == JNI_TRUE,
511            )?,
512        )
513    })
514}
515#[cfg(feature = "convert-rgb")]
516fn contiguous_rgb(frame: &Frame) -> Option<&[u8]> {
517    let layout = frame.layout();
518    let plane = layout.planes.first()?;
519    let row = usize::try_from(layout.width).ok()?.checked_mul(3)?;
520    let length = row.checked_mul(usize::try_from(layout.height).ok()?)?;
521    if layout.format != PixelFormat::Rgb8
522        || layout.bottom_up
523        || layout.planes.len() != 1
524        || plane.pixel_stride != 3
525        || plane.row_stride != row
526        || plane.length < length
527    {
528        return None;
529    }
530    frame
531        .bytes()
532        .get(plane.offset..plane.offset.checked_add(length)?)
533}
534
535#[cfg(feature = "convert-rgb")]
536fn rgb_to_android_argb(rgb: &[u8], output: &mut [u8]) -> Result<()> {
537    if !rgb.len().is_multiple_of(3) || output.len() < rgb.len() / 3 * 4 {
538        return Err(invalid("Invalid RGB/ARGB buffer lengths"));
539    }
540    let (source_pixels, _) = rgb.as_chunks::<3>();
541    let (target_pixels, _) = output.as_chunks_mut::<4>();
542    for (source, target) in source_pixels.iter().zip(target_pixels) {
543        let argb = 0xff00_0000
544            | (u32::from(source[0]) << 16)
545            | (u32::from(source[1]) << 8)
546            | u32::from(source[2]);
547        target.copy_from_slice(&argb.to_ne_bytes());
548    }
549    Ok(())
550}
551
552fn next_frame_into(
553    id: jlong,
554    pointer: *mut u8,
555    capacity: usize,
556    timeout_ms: jint,
557    android_argb: bool,
558) -> Result<Value> {
559    let handle = handle(id)?;
560    let current = session(&handle)?;
561    let native_output = handle.native_output.load(Ordering::Acquire);
562    if android_argb && native_output {
563        return Err(invalid(
564            "Android ARGB output requires an RGB capture session",
565        ));
566    }
567    let (frame, byte_length) = runtime().block_on(async {
568        let mut reader = handle.reader.lock().await;
569        if reader
570            .as_ref()
571            .is_none_or(|r| !Arc::ptr_eq(&r.session, &current))
572        {
573            *reader = Some(Reader {
574                frames: current.subscribe(SubscriptionOptions::latest())?,
575                session: current,
576                pending: None,
577                #[cfg(feature = "convert-rgb")]
578                converter: RgbConverter::new(),
579                #[cfg(feature = "convert-rgb")]
580                rgb: Vec::new(),
581            });
582        }
583        let reader = reader.as_mut().unwrap();
584        if reader.pending.is_none() {
585            reader.pending = Some(
586                reader
587                    .frames
588                    .next_timeout(Duration::from_millis(timeout_ms as u64))
589                    .await?,
590            );
591        }
592        let frame = reader.pending.as_ref().unwrap().clone();
593        let byte_length = if native_output {
594            let required = frame.bytes().len();
595            if capacity < required {
596                return Err(invalid(format!("Direct buffer needs {required} bytes")));
597            }
598            unsafe { std::ptr::copy_nonoverlapping(frame.bytes().as_ptr(), pointer, required) };
599            required
600        } else {
601            #[cfg(feature = "convert-rgb")]
602            {
603                let request = ConversionRequest::for_layout(frame.layout());
604                let rgb_length = request.output_len()?;
605                let required = if android_argb {
606                    rgb_length
607                        .checked_div(3)
608                        .and_then(|pixels| pixels.checked_mul(4))
609                        .ok_or_else(|| invalid("ARGB frame size overflow"))?
610                } else {
611                    rgb_length
612                };
613                if capacity < required {
614                    return Err(invalid(format!("Direct buffer needs {required} bytes")));
615                }
616                let output = unsafe { std::slice::from_raw_parts_mut(pointer, required) };
617                if let Some(rgb) = contiguous_rgb(&frame) {
618                    if android_argb {
619                        rgb_to_android_argb(rgb, output)?;
620                    } else {
621                        output.copy_from_slice(rgb);
622                    }
623                } else {
624                    reader.rgb.resize(rgb_length, 0);
625                    let Reader { converter, rgb, .. } = &mut *reader;
626                    converter.convert_into(&frame, request, rgb)?;
627                    if android_argb {
628                        rgb_to_android_argb(rgb, output)?;
629                    } else {
630                        output.copy_from_slice(rgb);
631                    }
632                }
633                required
634            }
635            #[cfg(not(feature = "convert-rgb"))]
636            unreachable!("RGB start is rejected when conversion is not compiled");
637        };
638        reader.pending.take();
639        Ok((frame, byte_length))
640    })?;
641    let layout = frame.layout();
642    let (pixel_format, planes) = if native_output {
643        (
644            format!("{:?}", layout.format),
645            layout.planes.iter().map(|p|json!({"offset":p.offset,"length":p.length,"rowStride":p.row_stride,"pixelStride":p.pixel_stride})).collect::<Vec<_>>(),
646        )
647    } else {
648        let pixel_stride = if android_argb { 4 } else { 3 };
649        (
650            if android_argb { "Argb8" } else { "Rgb8" }.to_owned(),
651            vec![
652                json!({"offset":0,"length":byte_length,"rowStride":layout.width as usize * pixel_stride,"pixelStride":pixel_stride}),
653            ],
654        )
655    };
656    Ok(
657        json!({"session":frame.key.session,"sequence":frame.key.sequence,"byteLength":byte_length,"width":layout.width,"height":layout.height,"pixelFormat":pixel_format,"planes":planes,"colorMatrix":format!("{:?}",layout.color.matrix),"colorRange":format!("{:?}",layout.color.range),"sourceTimestampNs":frame.source_timestamp_ns,"clock":frame.source_timestamp().map(|t|format!("{:?}",t.clock)),"rotation":layout.orientation.rotation_degrees,"mirrored":layout.orientation.mirrored,"bottomUp":if native_output {layout.bottom_up} else {false}}),
658    )
659}
660
661fn next_frame_boundary(
662    env: &mut JNIEnv<'_>,
663    id: jlong,
664    buffer: JByteBuffer,
665    timeout_ms: jint,
666    android_argb: bool,
667) -> Result<jstring> {
668    if !(0..=60000).contains(&timeout_ms) {
669        return Err(invalid("Frame timeout must be 0..60000 ms"));
670    }
671    if env.call_method(&buffer, "isReadOnly", "()Z", &[])?.z()? {
672        return Err(invalid("Frame buffer is read-only"));
673    }
674    let capacity = env.get_direct_buffer_capacity(&buffer)?;
675    let pointer = env.get_direct_buffer_address(&buffer)?;
676    output(
677        env,
678        next_frame_into(id, pointer, capacity, timeout_ms, android_argb)?,
679    )
680}
681
682/// The caller exclusively owns the direct buffer for the duration of this call.
683/// The adapter copies one frame and returns metadata in JSON. A small buffer
684/// leaves the frame pending, so callers may resize and retry without losing it.
685#[no_mangle]
686/// JNI entry point that copies the next frame into a direct byte buffer.
687pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeNextFrame(
688    mut env: JNIEnv,
689    _class: JClass,
690    id: jlong,
691    buffer: JByteBuffer,
692    timeout_ms: jint,
693) -> jstring {
694    boundary(&mut env, |env| {
695        next_frame_boundary(env, id, buffer, timeout_ms, false)
696    })
697}
698
699/// Writes native-endian ARGB words suitable for Bitmap.Config.ARGB_8888.
700#[no_mangle]
701/// JNI entry point that copies the next frame as Android-compatible ARGB pixels.
702pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeNextFrameArgb(
703    mut env: JNIEnv,
704    _class: JClass,
705    id: jlong,
706    buffer: JByteBuffer,
707    timeout_ms: jint,
708) -> jstring {
709    boundary(&mut env, |env| {
710        next_frame_boundary(env, id, buffer, timeout_ms, true)
711    })
712}
713#[no_mangle]
714/// JNI entry point that returns capture and delivery metrics as JSON.
715pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeMetrics(
716    mut env: JNIEnv,
717    _class: JClass,
718    id: jlong,
719) -> jstring {
720    boundary(&mut env, |env| {
721        let handle = handle(id)?;
722        let session = session(&handle)?;
723        let m = session.metrics();
724        let dropped = runtime().block_on(async {
725            handle
726                .reader
727                .lock()
728                .await
729                .as_ref()
730                .map(|r| r.frames.dropped_frames())
731                .unwrap_or(0)
732        });
733        output(
734            env,
735            json!({"received":m.received,"published":m.published,
736            "poolDrops":m.pool_drops,"conversionErrors":m.conversion_errors,
737            "allocatedBuffers":m.allocated_buffers,"allocatedBytes":m.allocated_bytes,
738            "retainedBuffers":m.retained_buffers,"conversionTotalNs":m.conversion_total_ns,
739            "conversionP50Ns":m.conversion_p50_ns,"conversionP95Ns":m.conversion_p95_ns,
740            "subscriberDrops":dropped,
741            "firstFrameLatencyMs":session.negotiated().first_frame_latency.as_secs_f64()*1000.0}),
742        )
743    })
744}
745
746#[no_mangle]
747/// JNI entry point that stops capture while retaining the camera handle.
748pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeStop(
749    mut env: JNIEnv,
750    _class: JClass,
751    id: jlong,
752) {
753    boundary(&mut env, |_| {
754        let handle = handle(id)?;
755        let _gate = handle
756            .lifecycle
757            .lock()
758            .map_err(|_| invalid("Lifecycle state poisoned"))?;
759        let session = handle
760            .session
761            .lock()
762            .map_err(|_| invalid("Session state poisoned"))?
763            .take();
764        if let Some(session) = session {
765            runtime().block_on(session.close())?;
766        }
767        Ok(())
768    })
769}
770#[no_mangle]
771/// JNI entry point that stops capture and releases the camera handle.
772pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeClose(
773    mut env: JNIEnv,
774    _class: JClass,
775    id: jlong,
776) {
777    boundary(&mut env, |_| {
778        let handle = registry()
779            .lock()
780            .map_err(|_| invalid("Handle registry poisoned"))?
781            .remove(&id);
782        if let Some(handle) = handle {
783            handle.closed.store(true, Ordering::Release);
784            let _gate = handle
785                .lifecycle
786                .lock()
787                .map_err(|_| invalid("Lifecycle state poisoned"))?;
788            let session = handle
789                .session
790                .lock()
791                .map_err(|_| invalid("Session state poisoned"))?
792                .take();
793            if let Some(session) = session {
794                runtime().block_on(session.close())?;
795            }
796        }
797        Ok(())
798    })
799}
800
801fn control_value_payload(value: ControlValue) -> Value {
802    match value {
803        ControlValue::Number(value) => json!(value),
804        ControlValue::Mode(value) => json!(format!("{value:?}")),
805    }
806}
807
808fn control_payload(control: camera::ControlDescriptor) -> Value {
809    json!({
810        "id":format!("{:?}",control.id),
811        "unit":format!("{:?}",control.unit),
812        "readable":control.readable,
813        "writable":control.writable,
814        "modes":control.modes.into_iter().map(|mode|format!("{mode:?}")).collect::<Vec<_>>(),
815        "range":control.range.map(|range|json!({
816            "min":range.min,
817            "max":range.max,
818            "step":range.step,
819            "default":range.default.map(control_value_payload)
820        })),
821        "requiresManual":control.requires_manual.map(|id|format!("{id:?}"))
822    })
823}
824
825#[no_mangle]
826/// JNI entry point that returns supported controls as JSON.
827pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeControls(
828    mut env: JNIEnv,
829    _class: JClass,
830    id: jlong,
831) -> jstring {
832    boundary(&mut env, |env| {
833        let session = session(&*handle(id)?)?;
834        let controls = runtime().block_on(session.controls())?;
835        output(
836            env,
837            json!(controls
838                .into_iter()
839                .map(control_payload)
840                .collect::<Vec<_>>()),
841        )
842    })
843}
844#[no_mangle]
845/// JNI entry point that reads a control value and its readback status.
846pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeControl(
847    mut env: JNIEnv,
848    _class: JClass,
849    id: jlong,
850    name: JString,
851) -> jstring {
852    boundary(&mut env, |env| {
853        let control = control_id(&text(env, name)?)?;
854        let value = runtime().block_on(session(&*handle(id)?)?.control(control))?;
855        let (kind, value) = match value {
856            camera::ControlReadback::Actual(value) => ("Actual", Some(value)),
857            camera::ControlReadback::Requested(value) => ("Requested", Some(value)),
858            camera::ControlReadback::Unknown => ("Unknown", None),
859        };
860        let value = value.map(control_value_payload);
861        output(env, json!({"kind":kind,"value":value}))
862    })
863}
864fn control_id(name: &str) -> Result<ControlId> {
865    use ControlId::*;
866    [
867        ExposureMode,
868        ExposureTime,
869        ExposureCompensation,
870        FocusMode,
871        FocusPosition,
872        WhiteBalanceMode,
873        WhiteBalanceTemperature,
874        Zoom,
875        Brightness,
876        Contrast,
877        Hue,
878        Saturation,
879        Sharpness,
880        Gamma,
881        BacklightCompensation,
882        Gain,
883        Pan,
884        Tilt,
885        Iris,
886    ]
887    .into_iter()
888    .find(|v| format!("{v:?}") == name)
889    .ok_or_else(|| invalid("Unknown control ID"))
890}
891#[no_mangle]
892/// JNI entry point that applies a numeric value or mode to a camera control.
893pub extern "system" fn Java_com_medivh_camera_MedivhCameraBridge_nativeSetControl(
894    mut env: JNIEnv,
895    _class: JClass,
896    id: jlong,
897    name: JString,
898    value: JString,
899) {
900    boundary(&mut env, |env| {
901        let control = control_id(&text(env, name)?)?;
902        let value: Value =
903            serde_json::from_str(&text(env, value)?).map_err(|e| invalid(e.to_string()))?;
904        let value = if let Some(n) = value.as_f64() {
905            ControlValue::Number(n)
906        } else {
907            let mode = match value.as_str() {
908                Some("Manual") => ControlMode::Manual,
909                Some("Automatic") => ControlMode::Automatic,
910                Some("Locked") => ControlMode::Locked,
911                Some("Single") => ControlMode::Single,
912                Some("Continuous") => ControlMode::Continuous,
913                _ => return Err(invalid("Control expects a JSON number or mode string")),
914            };
915            ControlValue::Mode(mode)
916        };
917        runtime().block_on(session(&*handle(id)?)?.set_control(control, value))?;
918        Ok(())
919    })
920}
921
922#[cfg(test)]
923mod demo_contract_tests {
924    use super::*;
925
926    #[test]
927    fn demo_supports_every_android_backend_and_capture_format() {
928        assert_eq!(backend("camera2").unwrap(), Some(BackendId::CAMERA2));
929        assert_eq!(backend("uvc").unwrap(), Some(BackendId::UVC));
930        assert_eq!(backend("v4l2").unwrap(), Some(BackendId::V4L2));
931        assert_eq!(
932            capture_format("Mjpeg").unwrap(),
933            camera::CaptureFormat::Mjpeg
934        );
935        assert_eq!(capture_format("Yuyv").unwrap(), camera::CaptureFormat::Yuyv);
936        assert_eq!(capture_format("Nv12").unwrap(), camera::CaptureFormat::Nv12);
937        assert!(capture_format("not-a-format").is_err());
938    }
939
940    #[test]
941    fn capability_payload_exposes_format_resolution_and_fractional_frame_rate() {
942        let capabilities = camera::DeviceCapabilities::single_native(
943            camera::CaptureFormat::Nv12,
944            1920,
945            1080,
946            FrameRate::new(30_000, 1_001).unwrap(),
947        );
948
949        let payload = capability_payload(capabilities);
950        let mode = &payload["modes"][0];
951        assert_eq!(payload["knowledge"], "known");
952        assert_eq!(mode["format"], "Nv12");
953        assert_eq!(mode["width"], 1920);
954        assert_eq!(mode["height"], 1080);
955        assert_eq!(mode["frameRateNumerator"], 30_000);
956        assert_eq!(mode["frameRateDenominator"], 1_001);
957    }
958
959    #[test]
960    fn control_payload_includes_the_reset_default() {
961        let descriptor = camera::ControlDescriptor {
962            id: ControlId::Brightness,
963            unit: camera::ControlUnit::Native,
964            readable: true,
965            writable: Some(true),
966            range: Some(camera::ControlRange {
967                min: 0.0,
968                max: 255.0,
969                step: Some(1.0),
970                default: Some(ControlValue::Number(128.0)),
971            }),
972            modes: Vec::new(),
973            requires_manual: None,
974        };
975
976        assert_eq!(control_payload(descriptor)["range"]["default"], 128.0);
977    }
978
979    #[test]
980    fn rgb_to_argb_uses_android_argb8888_native_words() {
981        let mut output = [0u8; 8];
982        rgb_to_android_argb(&[0x11, 0x22, 0x33, 0xaa, 0xbb, 0xcc], &mut output).unwrap();
983
984        assert_eq!(
985            u32::from_ne_bytes(output[0..4].try_into().unwrap()),
986            0xff11_2233
987        );
988        assert_eq!(
989            u32::from_ne_bytes(output[4..8].try_into().unwrap()),
990            0xffaa_bbcc
991        );
992    }
993}