Merge "Update the VDM documentation." into udc-dev

core/java/android/companion/virtual/IVirtualDevice.aidl

@@ -39,21 +39,22 @@ import android.hardware.input.VirtualNavigationTouchpadConfig;
 import android.os.ResultReceiver;
 
 /**
- * Interface for a virtual device.
+ * Interface for a virtual device for communication between the system server and the process of
+ * the owner of the virtual device.
  *
  * @hide
  */
 interface IVirtualDevice {
 
     /**
-     * Returns the association ID for this virtual device.
+     * Returns the CDM association ID of this virtual device.
      *
      * @see AssociationInfo#getId()
      */
     int getAssociationId();
 
     /**
-     * Returns the unique device ID for this virtual device.
+     * Returns the unique ID of this virtual device.
      */
     int getDeviceId();
 
@@ -64,55 +65,99 @@ interface IVirtualDevice {
     void close();
 
     /**
-     * Notifies of an audio session being started.
+     * Notifies that an audio session being started.
      */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
-    void onAudioSessionStarting(
+    void onAudioSessionStarting(int displayId, IAudioRoutingCallback routingCallback,
-            int displayId,
-            IAudioRoutingCallback routingCallback,
             IAudioConfigChangedCallback configChangedCallback);
 
+    /**
+     * Notifies that an audio session has ended.
+     */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
     void onAudioSessionEnded();
 
+    /**
+     * Creates a new dpad and registers it with the input framework with the given token.
+     */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
-    void createVirtualDpad(
+    void createVirtualDpad(in VirtualDpadConfig config, IBinder token);
-            in VirtualDpadConfig config,
+
-            IBinder token);
+    /**
+     * Creates a new keyboard and registers it with the input framework with the given token.
+     */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
-    void createVirtualKeyboard(
+    void createVirtualKeyboard(in VirtualKeyboardConfig config, IBinder token);
-            in VirtualKeyboardConfig config,
+
-            IBinder token);
+    /**
+     * Creates a new mouse and registers it with the input framework with the given token.
+     */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
-    void createVirtualMouse(
+    void createVirtualMouse(in VirtualMouseConfig config, IBinder token);
-            in VirtualMouseConfig config,
+
-            IBinder token);
+    /**
+     * Creates a new touchscreen and registers it with the input framework with the given token.
+     */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
-    void createVirtualTouchscreen(
+    void createVirtualTouchscreen(in VirtualTouchscreenConfig config, IBinder token);
-            in VirtualTouchscreenConfig config,
+
-            IBinder token);
+    /**
+     * Creates a new navigation touchpad and registers it with the input framework with the given
+     * token.
+     */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
-    void createVirtualNavigationTouchpad(
+    void createVirtualNavigationTouchpad(in VirtualNavigationTouchpadConfig config, IBinder token);
-            in VirtualNavigationTouchpadConfig config,
+
-            IBinder token);
+    /**
+     * Removes the input device corresponding to the given token from the framework.
+     */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
     void unregisterInputDevice(IBinder token);
+
+    /**
+     * Returns the ID of the device corresponding to the given token, as registered with the input
+     * framework.
+     */
     int getInputDeviceId(IBinder token);
+
+    /**
+    * Injects a key event to the virtual dpad corresponding to the given token.
+    */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
     boolean sendDpadKeyEvent(IBinder token, in VirtualKeyEvent event);
+
+    /**
+    * Injects a key event to the virtual keyboard corresponding to the given token.
+    */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
     boolean sendKeyEvent(IBinder token, in VirtualKeyEvent event);
+
+    /**
+    * Injects a button event to the virtual mouse corresponding to the given token.
+    */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
     boolean sendButtonEvent(IBinder token, in VirtualMouseButtonEvent event);
+
+    /**
+    * Injects a relative event to the virtual mouse corresponding to the given token.
+    */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
     boolean sendRelativeEvent(IBinder token, in VirtualMouseRelativeEvent event);
+
+    /**
+    * Injects a scroll event to the virtual mouse corresponding to the given token.
+    */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
     boolean sendScrollEvent(IBinder token, in VirtualMouseScrollEvent event);
+
+    /**
+    * Injects a touch event to the virtual touch input device corresponding to the given token.
+    */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
     boolean sendTouchEvent(IBinder token, in VirtualTouchEvent event);
 
     /**
-     * Returns all virtual sensors for this device.
+     * Returns all virtual sensors created for this device.
      */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
     List<VirtualSensor> getVirtualSensorList();
@@ -126,8 +171,13 @@ interface IVirtualDevice {
     /**
      * Launches a pending intent on the given display that is owned by this virtual device.
      */
-    void launchPendingIntent(
+    void launchPendingIntent(int displayId, in PendingIntent pendingIntent,
-            int displayId, in PendingIntent pendingIntent, in ResultReceiver resultReceiver);
+            in ResultReceiver resultReceiver);
+
+    /**
+     * Returns the current cursor position of the mouse corresponding to the given token, in x and y
+     * coordinates.
+     */
     PointF getCursorPosition(IBinder token);
 
     /** Sets whether to show or hide the cursor while this virtual device is active. */
@@ -140,8 +190,12 @@ interface IVirtualDevice {
      * intent.
      */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
-    void registerIntentInterceptor(
+    void registerIntentInterceptor(in IVirtualDeviceIntentInterceptor intentInterceptor,
-            in IVirtualDeviceIntentInterceptor intentInterceptor, in IntentFilter filter);
+            in IntentFilter filter);
+
+    /**
+     * Unregisters a previously registered intent interceptor.
+     */
     @EnforcePermission("CREATE_VIRTUAL_DEVICE")
     void unregisterIntentInterceptor(in IVirtualDeviceIntentInterceptor intentInterceptor);
 }

core/java/android/companion/virtual/VirtualDevice.java

@@ -26,6 +26,11 @@ import java.util.Objects;
 
 /**
  * Details of a particular virtual device.
+ *
+ * <p>Read-only device representation exposing the properties of an existing virtual device.
+ *
+ * <p class="note">Not to be confused with {@link VirtualDeviceManager.VirtualDevice}, which is used
+ * by the virtual device creator and allows them to manage the device.
  */
 public final class VirtualDevice implements Parcelable {
 

core/java/android/companion/virtual/VirtualDeviceManager.java

@@ -68,7 +68,13 @@ import java.util.concurrent.Executor;
 import java.util.function.IntConsumer;
 
 /**
- * System level service for managing virtual devices.
+ * System level service for creation and management of virtual devices.
+ *
+ * <p>VirtualDeviceManager enables interactive sharing of capabilities between the host Android
+ * device and a remote device.
+ *
+ * <p class="note">Not to be confused with the Android Studio's Virtual Device Manager, which allows
+ * for device emulation.
  */
 @SystemService(Context.VIRTUAL_DEVICE_SERVICE)
 public final class VirtualDeviceManager {
@@ -174,6 +180,9 @@ public final class VirtualDeviceManager {
 
     /**
      * Returns the details of all available virtual devices.
+     *
+     * <p>The returned objects are read-only representations that expose the properties of all
+     * existing virtual devices.
      */
     @NonNull
     public List<android.companion.virtual.VirtualDevice> getVirtualDevices() {
@@ -252,11 +261,12 @@ public final class VirtualDeviceManager {
      *
      * @param deviceId - id of the virtual audio device
      * @return Device specific session id to be used for audio playback (see
-     *     {@link android.media.AudioManager.generateAudioSessionId}) if virtual device has
+     *   {@link AudioManager#generateAudioSessionId}) if virtual device has
-     *     {@link VirtualDeviceParams.POLICY_TYPE_AUDIO} set to
+     *   {@link VirtualDeviceParams#POLICY_TYPE_AUDIO} set to
-     *     {@link VirtualDeviceParams.DEVICE_POLICY_CUSTOM} and Virtual Audio Device
+     *   {@link VirtualDeviceParams#DEVICE_POLICY_CUSTOM} and Virtual Audio Device
-     *     is configured in context-aware mode.
+     *   is configured in context-aware mode. Otherwise
-     *     Otherwise {@link AUDIO_SESSION_ID_GENERATE} constant is returned.
+     *   {@link AudioManager#AUDIO_SESSION_ID_GENERATE} constant is returned.
+     *
      * @hide
      */
     public int getAudioPlaybackSessionId(int deviceId) {
@@ -275,11 +285,12 @@ public final class VirtualDeviceManager {
      *
      * @param deviceId - id of the virtual audio device
      * @return Device specific session id to be used for audio recording (see
-     *     {@link android.media.AudioManager.generateAudioSessionId}) if virtual device has
+     *   {@link AudioManager#generateAudioSessionId}) if virtual device has
-     *     {@link VirtualDeviceParams.POLICY_TYPE_AUDIO} set to
+     *   {@link VirtualDeviceParams#POLICY_TYPE_AUDIO} set to
-     *     {@link VirtualDeviceParams.DEVICE_POLICY_CUSTOM} and Virtual Audio Device
+     *   {@link VirtualDeviceParams#DEVICE_POLICY_CUSTOM} and Virtual Audio Device
-     *     is configured in context-aware mode.
+     *   is configured in context-aware mode. Otherwise
-     *     Otherwise {@link AUDIO_SESSION_ID_GENERATE} constant is returned.
+     *   {@link AudioManager#AUDIO_SESSION_ID_GENERATE} constant is returned.
+     *
      * @hide
      */
     public int getAudioRecordingSessionId(int deviceId) {
@@ -296,10 +307,11 @@ public final class VirtualDeviceManager {
     /**
      * Requests sound effect to be played on virtual device.
      *
-     * @see android.media.AudioManager#playSoundEffect(int)
+     * @see AudioManager#playSoundEffect(int)
      *
      * @param deviceId - id of the virtual audio device
      * @param effectType the type of sound effect
+     *
      * @hide
      */
     public void playSoundEffect(int deviceId, @AudioManager.SystemSoundEffect int effectType) {
@@ -315,11 +327,18 @@ public final class VirtualDeviceManager {
     }
 
     /**
-     * A virtual device has its own virtual display, audio output, microphone, sensors, etc. The
+     * A representation of a virtual device.
-     * creator of a virtual device can take the output from the virtual display and stream it over
-     * to another device, and inject input events that are received from the remote device.
      *
-     * TODO(b/204081582): Consider using a builder pattern for the input APIs.
+     * <p>A virtual device can have its own virtual displays, audio input/output, sensors, etc.
+     * The creator of a virtual device can take the output from the virtual display and stream it
+     * over to another device, and inject input and sensor events that are received from the remote
+     * device.
+     *
+     * <p>This object is only used by the virtual device creator and allows them to manage the
+     * device's behavior, peripherals, and the user interaction with that device.
+     *
+     * <p class="note">Not to be confused with {@link android.companion.virtual.VirtualDevice},
+     * which is a read-only representation exposing the properties of an existing virtual device.
      *
      * @hide
      */
@@ -346,8 +365,10 @@ public final class VirtualDeviceManager {
         }
 
         /**
-         * @return A new Context bound to this device. This is a convenience method equivalent to
+         * Returns a new context bound to this device.
-         * calling {@link Context#createDeviceContext(int)} with the device id of this device.
+         *
+         * <p>This is a convenience method equivalent to calling
+         * {@link Context#createDeviceContext(int)} with the id of this device.
          */
         public @NonNull Context createContext() {
             return mVirtualDeviceInternal.createContext();
@@ -400,17 +421,16 @@ public final class VirtualDeviceManager {
          * @param height The height of the virtual display in pixels, must be greater than 0.
          * @param densityDpi The density of the virtual display in dpi, must be greater than 0.
          * @param surface The surface to which the content of the virtual display should
-         * be rendered, or null if there is none initially. The surface can also be set later using
+         *   be rendered, or null if there is none initially. The surface can also be set later
-         * {@link VirtualDisplay#setSurface(Surface)}.
+         *   using {@link VirtualDisplay#setSurface(Surface)}.
          * @param flags A combination of virtual display flags accepted by
          *   {@link DisplayManager#createVirtualDisplay}. In addition, the following flags are
          *   automatically set for all virtual devices:
-         * {@link DisplayManager#VIRTUAL_DISPLAY_FLAG_PUBLIC VIRTUAL_DISPLAY_FLAG_PUBLIC} and
+         *   {@link DisplayManager#VIRTUAL_DISPLAY_FLAG_PUBLIC} and
-         * {@link DisplayManager#VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY
+         *   {@link DisplayManager#VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY}.
-         * VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY}.
          * @param executor The executor on which {@code callback} will be invoked. This is ignored
-         * if {@code callback} is {@code null}. If {@code callback} is specified, this executor must
+         *   if {@code callback} is {@code null}. If {@code callback} is specified, this executor
-         * not be null.
+         *   must not be null.
          * @param callback Callback to call when the state of the {@link VirtualDisplay} changes
          * @return The newly created virtual display, or {@code null} if the application could
          *   not create the virtual display.
@@ -450,8 +470,8 @@ public final class VirtualDeviceManager {
          *
          * @param config The configuration of the display.
          * @param executor The executor on which {@code callback} will be invoked. This is ignored
-         * if {@code callback} is {@code null}. If {@code callback} is specified, this executor must
+         *   if {@code callback} is {@code null}. If {@code callback} is specified, this executor
-         * not be null.
+         *   must not be null.
          * @param callback Callback to call when the state of the {@link VirtualDisplay} changes
          * @return The newly created virtual display, or {@code null} if the application could
          *   not create the virtual display.
@@ -478,7 +498,7 @@ public final class VirtualDeviceManager {
         /**
          * Creates a virtual dpad.
          *
-         * @param config the configurations of the virtual Dpad.
+         * @param config the configurations of the virtual dpad.
          */
         @RequiresPermission(android.Manifest.permission.CREATE_VIRTUAL_DEVICE)
         @NonNull
@@ -500,11 +520,10 @@ public final class VirtualDeviceManager {
         /**
          * Creates a virtual keyboard.
          *
-         * @param display         the display that the events inputted through this device should
+         * @param display the display that the events inputted through this device should target.
-         *                        target
+         * @param inputDeviceName the name of this keyboard device.
-         * @param inputDeviceName the name to call this input device
+         * @param vendorId the PCI vendor id.
-         * @param vendorId        the PCI vendor id
+         * @param productId the product id, as defined by the vendor.
-         * @param productId       the product id, as defined by the vendor
          * @see #createVirtualKeyboard(VirtualKeyboardConfig config)
          * @deprecated Use {@link #createVirtualKeyboard(VirtualKeyboardConfig config)} instead
          */
@@ -537,14 +556,12 @@ public final class VirtualDeviceManager {
         /**
          * Creates a virtual mouse.
          *
-         * @param display         the display that the events inputted through this device should
+         * @param display the display that the events inputted through this device should target.
-         *                        target
+         * @param inputDeviceName the name of this mouse.
-         * @param inputDeviceName the name to call this input device
+         * @param vendorId the PCI vendor id.
-         * @param vendorId        the PCI vendor id
+         * @param productId the product id, as defined by the vendor.
-         * @param productId       the product id, as defined by the vendor
          * @see #createVirtualMouse(VirtualMouseConfig config)
          * @deprecated Use {@link #createVirtualMouse(VirtualMouseConfig config)} instead
-         * *
          */
         @Deprecated
         @RequiresPermission(android.Manifest.permission.CREATE_VIRTUAL_DEVICE)
@@ -576,11 +593,10 @@ public final class VirtualDeviceManager {
         /**
          * Creates a virtual touchscreen.
          *
-         * @param display         the display that the events inputted through this device should
+         * @param display the display that the events inputted through this device should target.
-         *                        target
+         * @param inputDeviceName the name of this touchscreen device.
-         * @param inputDeviceName the name to call this input device
+         * @param vendorId the PCI vendor id.
-         * @param vendorId        the PCI vendor id
+         * @param productId the product id, as defined by the vendor.
-         * @param productId       the product id, as defined by the vendor
          * @see #createVirtualTouchscreen(VirtualTouchscreenConfig config)
          * @deprecated Use {@link #createVirtualTouchscreen(VirtualTouchscreenConfig config)}
          * instead
@@ -605,11 +621,13 @@ public final class VirtualDeviceManager {
         /**
          * Creates a virtual touchpad in navigation mode.
          *
-         * A touchpad in navigation mode means that its events are interpreted as navigation events
+         * <p>A touchpad in navigation mode means that its events are interpreted as navigation
-         * (up, down, etc) instead of using them to update a cursor's absolute position. If the
+         * events (up, down, etc) instead of using them to update a cursor's absolute position. If
-         * events are not consumed they are converted to DPAD events.
+         * the events are not consumed they are converted to DPAD events and delivered to the target
+         * again.
          *
          * @param config the configurations of the virtual navigation touchpad.
+         * @see android.view.InputDevice#SOURCE_TOUCH_NAVIGATION
          */
         @RequiresPermission(android.Manifest.permission.CREATE_VIRTUAL_DEVICE)
         @NonNull
@@ -629,8 +647,8 @@ public final class VirtualDeviceManager {
          *
          * @param display The target virtual display to capture from and inject into.
          * @param executor The {@link Executor} object for the thread on which to execute
-         *                the callback. If <code>null</code>, the {@link Executor} associated with
+         *   the callback. If <code>null</code>, the {@link Executor} associated with the main
-         *                the main {@link Looper} will be used.
+         *   {@link Looper} will be used.
          * @param callback Interface to be notified when playback or recording configuration of
          *   applications running on virtual display is changed.
          * @return A {@link VirtualAudioDevice} instance.
@@ -670,8 +688,7 @@ public final class VirtualDeviceManager {
         }
 
         /**
-         * Removes an activity listener previously added with
+         * Removes an activity listener previously added with {@link #addActivityListener}.
-         * {@link #addActivityListener}.
          *
          * @param listener The listener to remove.
          * @see #addActivityListener(Executor, ActivityListener)
@@ -693,10 +710,10 @@ public final class VirtualDeviceManager {
         }
 
         /**
-         * Removes a sound effect listener previously added with {@link #addActivityListener}.
+         * Removes a sound effect listener previously added with {@link #addSoundEffectListener}.
          *
          * @param soundEffectListener The listener to remove.
-         * @see #addActivityListener(Executor, ActivityListener)
+         * @see #addSoundEffectListener(Executor, SoundEffectListener)
          */
         public void removeSoundEffectListener(@NonNull SoundEffectListener soundEffectListener) {
             mVirtualDeviceInternal.removeSoundEffectListener(soundEffectListener);
@@ -723,7 +740,7 @@ public final class VirtualDeviceManager {
         }
 
         /**
-         * Unregisters the intent interceptorCallback previously registered with
+         * Unregisters the intent interceptor previously registered with
          * {@link #registerIntentInterceptor}.
          */
         @RequiresPermission(android.Manifest.permission.CREATE_VIRTUAL_DEVICE)
@@ -800,6 +817,7 @@ public final class VirtualDeviceManager {
 
     /**
      * Listener for system sound effect playback on virtual device.
+     *
      * @hide
      */
     @SystemApi
@@ -808,8 +826,8 @@ public final class VirtualDeviceManager {
         /**
          * Called when there's a system sound effect to be played on virtual device.
          *
-         * @param effectType - system sound effect type, see
+         * @param effectType - system sound effect type
-         *     {@code android.media.AudioManager.SystemSoundEffect}
+         * @see android.media.AudioManager.SystemSoundEffect
          */
         void onPlaySoundEffect(@AudioManager.SystemSoundEffect int effectType);
     }

core/java/android/companion/virtual/VirtualDeviceParams.java

@@ -34,6 +34,7 @@ import android.companion.virtual.sensor.VirtualSensorCallback;
 import android.companion.virtual.sensor.VirtualSensorConfig;
 import android.companion.virtual.sensor.VirtualSensorDirectChannelCallback;
 import android.content.ComponentName;
+import android.content.Context;
 import android.os.Parcel;
 import android.os.Parcelable;
 import android.os.SharedMemory;
@@ -680,7 +681,7 @@ public final class VirtualDeviceParams implements Parcelable {
          * {@link #NAVIGATION_POLICY_DEFAULT_ALLOWED}, meaning activities are allowed to launch
          * unless they are in {@code blockedCrossTaskNavigations}.
          *
-         * <p> This method must not be called if {@link #setAllowedCrossTaskNavigations(Set)} has
+         * <p>This method must not be called if {@link #setAllowedCrossTaskNavigations(Set)} has
          * been called.
          *
          * @throws IllegalArgumentException if {@link #setAllowedCrossTaskNavigations(Set)} has
@@ -847,11 +848,11 @@ public final class VirtualDeviceParams implements Parcelable {
          * <p>Requires {@link #DEVICE_POLICY_CUSTOM} to be set for {@link #POLICY_TYPE_AUDIO},
          * otherwise {@link #build()} method will throw {@link IllegalArgumentException} if
          * the playback session id is set to value other than
-         * {@link android.media.AudioManager.AUDIO_SESSION_ID_GENERATE}.
+         * {@link android.media.AudioManager#AUDIO_SESSION_ID_GENERATE}.
          *
          * @param playbackSessionId requested device-specific audio session id for playback
-         * @see android.media.AudioManager.generateAudioSessionId()
+         * @see android.media.AudioManager#generateAudioSessionId()
-         * @see android.media.AudioTrack.Builder.setContext(Context)
+         * @see android.media.AudioTrack.Builder#setContext(Context)
          */
         @NonNull
         public Builder setAudioPlaybackSessionId(int playbackSessionId) {
@@ -871,11 +872,11 @@ public final class VirtualDeviceParams implements Parcelable {
          * <p>Requires {@link #DEVICE_POLICY_CUSTOM} to be set for {@link #POLICY_TYPE_AUDIO},
          * otherwise {@link #build()} method will throw {@link IllegalArgumentException} if
          * the recording session id is set to value other than
-         * {@link android.media.AudioManager.AUDIO_SESSION_ID_GENERATE}.
+         * {@link android.media.AudioManager#AUDIO_SESSION_ID_GENERATE}.
          *
          * @param recordingSessionId requested device-specific audio session id for playback
-         * @see android.media.AudioManager.generateAudioSessionId()
+         * @see android.media.AudioManager#generateAudioSessionId()
-         * @see android.media.AudioRecord.Builder.setContext(Context)
+         * @see android.media.AudioRecord.Builder#setContext(Context)
          */
         @NonNull
         public Builder setAudioRecordingSessionId(int recordingSessionId) {

core/java/android/companion/virtual/audio/AudioCapture.java

@@ -56,12 +56,12 @@ public final class AudioCapture {
 
     /**
      * Sets the {@link AudioRecord} to handle audio capturing.
-     * Callers may call this multiple times with different audio records to change
-     * the underlying {@link AudioRecord} without stopping and re-starting recording.
      *
-     * @param audioRecord The underlying {@link AudioRecord} to use for capture,
+     * <p>Callers may call this multiple times with different audio records to change the underlying
-     * or null if no audio (i.e. silence) should be captured while still keeping the
+     * {@link AudioRecord} without stopping and re-starting recording.
-     * record in a recording state.
+     *
+     * @param audioRecord The underlying {@link AudioRecord} to use for capture, or null if no audio
+     *   (i.e. silence) should be captured while still keeping the record in a recording state.
      */
     void setAudioRecord(@Nullable AudioRecord audioRecord) {
         Log.d(TAG, "set AudioRecord with " + audioRecord);

core/java/android/companion/virtual/audio/AudioInjection.java

@@ -65,12 +65,12 @@ public final class AudioInjection {
 
     /**
      * Sets the {@link AudioTrack} to handle audio injection.
-     * Callers may call this multiple times with different audio tracks to change
-     * the underlying {@link AudioTrack} without stopping and re-starting injection.
      *
-     * @param audioTrack The underlying {@link AudioTrack} to use for injection,
+     * <p>Callers may call this multiple times with different audio tracks to change the underlying
-     * or null if no audio (i.e. silence) should be injected while still keeping the
+     * {@link AudioTrack} without stopping and re-starting injection.
-     * record in a playing state.
+     *
+     * @param audioTrack The underlying {@link AudioTrack} to use for injection, or null if no audio
+     *   (i.e. silence) should be injected while still keeping the record in a playing state.
      */
     void setAudioTrack(@Nullable AudioTrack audioTrack) {
         Log.d(TAG, "set AudioTrack with " + audioTrack);

core/java/android/companion/virtual/sensor/VirtualSensor.java

@@ -30,7 +30,7 @@ import android.os.RemoteException;
  * Representation of a sensor on a remote device, capable of sending events, such as an
  * accelerometer or a gyroscope.
  *
- * This registers the sensor device with the sensor framework as a runtime sensor.
+ * <p>A virtual sensor device is registered with the sensor framework as a runtime sensor.
  *
  * @hide
  */

core/java/android/companion/virtual/sensor/VirtualSensorConfig.java

@@ -31,7 +31,9 @@ import java.util.Objects;
 
 /**
  * Configuration for creation of a virtual sensor.
+ *
  * @see VirtualSensor
+ *
  * @hide
  */
 @SystemApi
@@ -122,6 +124,7 @@ public final class VirtualSensorConfig implements Parcelable {
 
     /**
      * Returns the vendor string of the sensor.
+     *
      * @see Builder#setVendor
      */
     @Nullable
@@ -130,7 +133,8 @@ public final class VirtualSensorConfig implements Parcelable {
     }
 
     /**
-     * Returns maximum range of the sensor in the sensor's unit.
+     * Returns the maximum range of the sensor in the sensor's unit.
+     *
      * @see Sensor#getMaximumRange
      */
     public float getMaximumRange() {
@@ -138,7 +142,8 @@ public final class VirtualSensorConfig implements Parcelable {
     }
 
     /**
-     * Returns The resolution of the sensor in the sensor's unit.
+     * Returns the resolution of the sensor in the sensor's unit.
+     *
      * @see Sensor#getResolution
      */
     public float getResolution() {
@@ -146,7 +151,8 @@ public final class VirtualSensorConfig implements Parcelable {
     }
 
     /**
-     * Returns The power in mA used by this sensor while in use.
+     * Returns the power in mA used by this sensor while in use.
+     *
      * @see Sensor#getPower
      */
     public float getPower() {
@@ -154,8 +160,9 @@ public final class VirtualSensorConfig implements Parcelable {
     }
 
     /**
-     * Returns The minimum delay allowed between two events in microseconds, or zero depending on
+     * Returns the minimum delay allowed between two events in microseconds, or zero depending on
      * the sensor type.
+     *
      * @see Sensor#getMinDelay
      */
     public int getMinDelay() {
@@ -163,7 +170,8 @@ public final class VirtualSensorConfig implements Parcelable {
     }
 
     /**
-     * Returns The maximum delay between two sensor events in microseconds.
+     * Returns the maximum delay between two sensor events in microseconds.
+     *
      * @see Sensor#getMaxDelay
      */
     public int getMaxDelay() {
@@ -201,6 +209,7 @@ public final class VirtualSensorConfig implements Parcelable {
 
     /**
      * Returns the sensor flags.
+     *
      * @hide
      */
     public int getFlags() {
@@ -275,6 +284,7 @@ public final class VirtualSensorConfig implements Parcelable {
 
         /**
          * Sets the maximum range of the sensor in the sensor's unit.
+         *
          * @see Sensor#getMaximumRange
          */
         @NonNull
@@ -285,6 +295,7 @@ public final class VirtualSensorConfig implements Parcelable {
 
         /**
          * Sets the resolution of the sensor in the sensor's unit.
+         *
          * @see Sensor#getResolution
          */
         @NonNull
@@ -295,6 +306,7 @@ public final class VirtualSensorConfig implements Parcelable {
 
         /**
          * Sets the power in mA used by this sensor while in use.
+         *
          * @see Sensor#getPower
          */
         @NonNull
@@ -305,6 +317,7 @@ public final class VirtualSensorConfig implements Parcelable {
 
         /**
          * Sets the minimum delay allowed between two events in microseconds.
+         *
          * @see Sensor#getMinDelay
          */
         @NonNull
@@ -315,6 +328,7 @@ public final class VirtualSensorConfig implements Parcelable {
 
         /**
          * Sets the maximum delay between two sensor events in microseconds.
+         *
          * @see Sensor#getMaxDelay
          */
         @NonNull
@@ -340,8 +354,8 @@ public final class VirtualSensorConfig implements Parcelable {
          *
          * @param memoryTypes A combination of {@link SensorDirectChannel.MemoryType} flags
          *   indicating the types of shared memory supported for creating direct channels. Only
-         * {@link SensorDirectChannel#TYPE_MEMORY_FILE} direct channels may be supported for virtual
+         *   {@link SensorDirectChannel#TYPE_MEMORY_FILE} direct channels may be supported for
-         * sensors.
+         *   virtual sensors.
          * @throws IllegalArgumentException if {@link SensorDirectChannel#TYPE_HARDWARE_BUFFER} is
          *   set to be supported.
          */

core/java/android/companion/virtual/sensor/VirtualSensorDirectChannelCallback.java

@@ -45,6 +45,8 @@ import android.os.SharedMemory;
  * <p>The callback is tied to the VirtualDevice's lifetime as the virtual sensors are created when
  * the device is created and destroyed when the device is destroyed.
  *
+ * @see VirtualSensorDirectChannelWriter
+ *
  * @hide
  */
 @SystemApi

core/java/android/companion/virtual/sensor/VirtualSensorDirectChannelWriter.java

@@ -41,6 +41,41 @@ import java.util.concurrent.atomic.AtomicLong;
  * write the events from the relevant sensors directly to the shared memory regions of the
  * corresponding {@link SensorDirectChannel} instances.
  *
+ * <p>Example:
+ * <p>During sensor and virtual device creation:
+ * <pre>
+ * VirtualSensorDirectChannelWriter writer = new VirtualSensorDirectChannelWriter();
+ * VirtualSensorDirectChannelCallback callback = new VirtualSensorDirectChannelCallback() {
+ *     @Override
+ *     public void onDirectChannelCreated(int channelHandle, SharedMemory sharedMemory) {
+ *         writer.addChannel(channelHandle, sharedMemory);
+ *     }
+ *     @Override
+ *     public void onDirectChannelDestroyed(int channelHandle);
+ *         writer.removeChannel(channelHandle);
+ *     }
+ *     @Override
+ *     public void onDirectChannelConfigured(int channelHandle, VirtualSensor sensor, int rateLevel,
+ *             int reportToken)
+ *         if (!writer.configureChannel(channelHandle, sensor, rateLevel, reportToken)) {
+ *              // handle error
+ *         }
+ *     }
+ * }
+ * </pre>
+ * <p>During the virtual device lifetime:
+ * <pre>
+ * VirtualSensor sensor = ...
+ * while (shouldInjectEvents(sensor)) {
+ *     if (!writer.writeSensorEvent(sensor, event)) {
+ *         // handle error
+ *     }
+ * }
+ * writer.close();
+ * </pre>
+ * <p>Note that the virtual device owner should take the currently configured rate level into
+ * account when deciding whether and how often to inject events for a particular sensor.
+ *
  * @see android.hardware.SensorDirectChannel#configure
  * @see VirtualSensorDirectChannelCallback
  *

core/java/android/companion/virtual/sensor/VirtualSensorEvent.java

@@ -121,7 +121,7 @@ public final class VirtualSensorEvent implements Parcelable {
          * monotonically increasing using the same time base as
          * {@link android.os.SystemClock#elapsedRealtimeNanos()}.
          *
-         * If not explicitly set, the current timestamp is used for the sensor event.
+         * <p>If not explicitly set, the current timestamp is used for the sensor event.
          *
          * @see android.hardware.SensorEvent#timestamp
          */