docs: documentation for MediaStreamTrack, VideoBufferConverter, and VideoCapture

Author: devopvoid

webrtc/src/main/java/dev/onvoid/webrtc/media/MediaStreamTrack.java

@@ -20,9 +20,9 @@
 
 /**
  * The MediaStreamTrack represents media of a single type that originates from
- * one media source, e.g. video produced by a web camera.
+ * one media source, e.g., video produced by a web camera.
  *
- * @link https://www.w3.org/TR/mediacapture-streams/#mediastreamtrack
+ * @link <a href="https://www.w3.org/TR/mediacapture-streams/#mediastreamtrack">...</a>
  *
  * @author Alex Andres
  */
@@ -100,7 +100,7 @@ public void removeTrackEndedListener(MediaStreamTrackEndedListener listener) {
 
 	/**
 	 * When a MediaStreamTrack is created, the application must generate an
-	 * identifier string, and must initialize the object's id attribute to that
+	 * identifier string. It must initialize the object's id attribute to that
 	 * string, unless the object is created as part of a special purpose
 	 * algorithm that specifies how the stream id must be initialized.
 	 *
@@ -119,7 +119,7 @@ public void removeTrackEndedListener(MediaStreamTrackEndedListener listener) {
 	 * Controls the enabled state for the media track. A disabled track will
 	 * produce silence (if audio) or black frames (if video). After a
 	 * MediaStreamTrack has ended, its enabled attribute still changes value
-	 * when set; it just doesn't do anything wit that new value.
+	 * when set; it just doesn't do anything with that new value.
 	 *
 	 * @param enable The new value.
 	 */

webrtc/src/main/java/dev/onvoid/webrtc/media/video/VideoBufferConverter.java

@@ -16,12 +16,33 @@
 
 package dev.onvoid.webrtc.media.video;
 
-import dev.onvoid.webrtc.media.FourCC;
-
 import java.nio.ByteBuffer;
 
+import dev.onvoid.webrtc.media.FourCC;
+
+/**
+ * Utility methods to convert between I420 video frame buffers and other pixel
+ * formats represented by a FourCC. Delegates actual conversion work to native
+ * methods for performance.
+ *
+ * @author Alex Andres
+ */
 public final class VideoBufferConverter {
 
+	/**
+	 * Convert an arbitrary {@link VideoFrameBuffer} to the specified pixel format
+	 * (given by {@code fourCC}) and write the result into a destination byte array.
+	 * <p>
+	 * The source buffer is first converted (if necessary) to an intermediate
+	 * I420 layout via {@link VideoFrameBuffer#toI420()} and then transformed.
+	 *
+	 * @param src    Source video frame buffer (will be converted to I420 if not already).
+	 * @param dst    Destination byte array expected to be large enough to hold the converted frame.
+	 * @param fourCC Target FourCC format identifier.
+	 *
+	 * @throws NullPointerException if {@code src} or {@code dst} is {@code null}.
+	 * @throws Exception            if the native conversion fails.
+	 */
 	public static void convertFromI420(VideoFrameBuffer src, byte[] dst, FourCC fourCC) throws Exception {
 		if (src == null) {
 			throw new NullPointerException("Source buffer must not be null");
@@ -40,7 +61,21 @@ public static void convertFromI420(VideoFrameBuffer src, byte[] dst, FourCC four
 				i420.getWidth(), i420.getHeight(),
 				fourCC.value());
 	}
-	
+
+	/**
+	 * Convert an arbitrary {@link VideoFrameBuffer} to the specified pixel format
+	 * and write the result into a {@link ByteBuffer}. If the destination buffer
+	 * is a direct buffer, a native direct path is used; otherwise its backing
+	 * array (or a temporary array) is employed.
+	 *
+	 * @param src    Source video frame buffer.
+	 * @param dst    Writable destination {@link ByteBuffer}. Must not be read-only.
+	 * @param fourCC Target FourCC format identifier.
+	 *
+	 * @throws NullPointerException     if {@code src} or {@code dst} is {@code null}.
+	 * @throws IllegalArgumentException if {@code dst} is read-only.
+	 * @throws Exception                if the native conversion fails.
+	 */
 	public static void convertFromI420(VideoFrameBuffer src, ByteBuffer dst, FourCC fourCC) throws Exception {
 		if (src == null) {
 			throw new NullPointerException("Source buffer must not be null");
@@ -84,6 +119,17 @@ public static void convertFromI420(VideoFrameBuffer src, ByteBuffer dst, FourCC
 		}
 	}
 
+	/**
+	 * Convert a source frame stored in a byte array (encoded in the format indicated
+	 * by {@code fourCC}) to I420 and write the planes into the provided {@link I420Buffer}.
+	 *
+	 * @param src    Source pixel data in the specified FourCC format.
+	 * @param dst    Destination I420 buffer (pre-allocated).
+	 * @param fourCC FourCC describing the layout of {@code src}.
+	 *
+	 * @throws NullPointerException if {@code src} or {@code dst} is {@code null}.
+	 * @throws Exception            if the native conversion fails.
+	 */
 	public static void convertToI420(byte[] src, I420Buffer dst, FourCC fourCC) throws Exception {
 		if (src == null) {
 			throw new NullPointerException("Source buffer must not be null");
@@ -101,6 +147,19 @@ public static void convertToI420(byte[] src, I420Buffer dst, FourCC fourCC) thro
 				fourCC.value());
 	}
 
+	/**
+	 * Convert a source frame stored in a {@link ByteBuffer} (encoded in the format
+	 * specified by {@code fourCC}) to I420 and write the result into the provided
+	 * {@link I420Buffer}. Uses a direct native path for direct buffers; otherwise
+	 * reads from the backing or a temporary array.
+	 *
+	 * @param src    Source pixel data buffer.
+	 * @param dst    Destination I420 buffer (pre-allocated).
+	 * @param fourCC FourCC describing the layout of {@code src}.
+	 *
+	 * @throws NullPointerException if {@code src} or {@code dst} is {@code null}.
+	 * @throws Exception            if the native conversion fails.
+	 */
 	public static void convertToI420(ByteBuffer src, I420Buffer dst, FourCC fourCC) throws Exception {
 		if (src == null) {
 			throw new NullPointerException("Source buffer must not be null");

webrtc/src/main/java/dev/onvoid/webrtc/media/video/VideoCapture.java

@@ -18,24 +18,122 @@
 
 import dev.onvoid.webrtc.internal.NativeObject;
 
+/**
+ * A class representing a video capture device that can be controlled to capture video.
+ * Extends NativeObject to interact with native code implementations.
+ * <pre>
+ * VideoCapture capture = new VideoCapture();
+ * capture.setVideoCaptureDevice(device);
+ * capture.setVideoCaptureCapability(capability);
+ * capture.setVideoSink(sink);
+ * capture.start();
+ * // ... consume frames via sink ...
+ * capture.stop();
+ * capture.dispose();
+ * </pre>
+ * Notes:
+ * <li>Always call dispose() to release native resources.</li>
+ * <li>Methods are not guaranteed to be thread-safe unless externally synchronized.</li>
+ *
+ * @author Alex Andres
+ */
 public class VideoCapture extends NativeObject {
 
+	/**
+	 * Constructs a new VideoCapture and initializes underlying native resources.
+	 * Initialization failures are typically surfaced as runtime exceptions
+	 * originating from native code.
+	 */
 	public VideoCapture() {
 		initialize();
 	}
 
+	/**
+	 * Selects the physical (or virtual) video input device to capture from.
+	 * <p>
+	 * Constraints / Lifecycle:
+	 * <li>Must be invoked before {@link #start()}.</li>
+	 * <li>Re-setting the device after capture has started may require an
+	 *     internal restart (implementation-dependent).</li>
+	 *
+	 * @param device Non-null device descriptor to bind. Passing {@code null}
+	 *               is invalid and may raise a {@link NullPointerException}.
+	 *
+	 * @throws IllegalStateException if called after disposal.
+	 */
 	public native void setVideoCaptureDevice(VideoDevice device);
 
+	/**
+	 * Defines desired capture parameters (resolution, frame rate, pixel format, etc.).
+	 * <p>
+	 * Constraints:
+	 * <li>Should be called after selecting the device and before {@link #start()}.</li>
+	 * <li>Some capabilities may be adjusted (e.g., negotiated to the nearest supported values).</li>
+	 *
+	 * @param capability Desired capture capability (must be non-null).
+	 *
+	 * @throws IllegalArgumentException if unsupported or invalid.
+	 * @throws IllegalStateException    if called after disposal.
+	 */
 	public native void setVideoCaptureCapability(VideoCaptureCapability capability);
 
+	/**
+	 * Registers (or replaces) the sink that will receive decoded/raw video frames.
+	 * <p>
+	 * Behavior:
+	 * <li>May be called before or after {@link #start()}.</li>
+	 * <li>Passing {@code null} (if supported) detaches the current sink and
+	 *     frames will be dropped until a new sink is set.</li>
+	 *
+	 * @param sink The consumer of captured frames.
+	 *
+	 * @throws IllegalStateException if called after disposal.
+	 */
 	public native void setVideoSink(VideoTrackSink sink);
 
+	/**
+	 * Begins asynchronous frame capture and delivery to the configured sink.
+	 * <p>
+	 * Idempotency:
+	 * Calling start() while already started should be a no-op (implementation-dependent).
+	 *
+	 * @throws IllegalStateException if prerequisites (device/capability) are missing
+	 *                               or the instance is disposed.
+	 */
 	public native void start();
 
+	/**
+	 * Stops frame capture.
+	 * <p>
+	 * Behavior:
+	 * <li>Drains or discards in-flight frames (implementation-dependent).</li>
+	 * <li>Safe to call multiple times (idempotent).</li>
+	 *
+	 * @throws IllegalStateException if the instance is disposed.
+	 */
 	public native void stop();
 
+	/**
+	 * Releases native resources associated with this capture instance.
+	 * <p>
+	 * Lifecycle:
+	 * <li>Implicitly stops capture if currently running.</li>
+	 * <li>After disposal, further method calls (other than additional dispose attempts)
+	 *     are invalid and may throw {@link IllegalStateException}.</li>
+	 * <p>
+	 * Best Practice:
+	 * Always invoke in a finally block or use a higher-level resource management
+	 * construct to avoid native leaks.
+	 */
 	public native void dispose();
 
+	/**
+	 * Internal native initialization hook invoked exactly once by the constructor.
+	 * Not intended for direct external use.
+	 * <p>
+	 * Failure Handling:
+	 * Should raise a runtime exception if initialization fails.
+	 */
 	private native void initialize();
 
 }