feat(planecontrol,videodecoder)!: the capture plane owns capture end to end (#753)

planecontrol/current/com/rdk/hal/planecontrol/IPlaneControl.aidl

@@ -24,8 +24,10 @@ import com.rdk.hal.planecontrol.SourcePlaneMapping;
 import com.rdk.hal.planecontrol.Property;
 import com.rdk.hal.planecontrol.PropertyKVPair;
 import com.rdk.hal.PropertyValue;
-import com.rdk.hal.planecontrol.IGraphicsFbProvider;
-import com.rdk.hal.planecontrol.IGraphicsFbProviderListener;
+import com.rdk.hal.planecontrol.graphics.IGraphicsFbProvider;
+import com.rdk.hal.planecontrol.graphics.IGraphicsFbProviderListener;
+import com.rdk.hal.planecontrol.capture.ICapture;
+import com.rdk.hal.planecontrol.capture.ICaptureEventListener;
 
 
 /** 
@@ -68,6 +70,12 @@ interface IPlaneControl
      * Operations such as main and PIP video swaps can be performed using this call.
      * 
      * To unmap a source from its plane, map it to a `destinationPlaneIndex` of -1.
+     *
+     * A plane of type `PlaneType.CAPTURE` is a destination like any other, and mapping a
+     * source to one is what routes that source's decoded frames to capture. The frames
+     * are then delivered to the client through `getCapture()` rather than displayed.
+     * Unmapping a source from a capture plane while a session is running stops that
+     * session and raises `ICaptureEventListener.onSourceUnmapped()`.
      * 
      * If a source type and source index appear multiple times in the mapping list then the call fails.
      * If a plane index appears multiple times in the mapping list then the call fails.
@@ -83,7 +91,7 @@ interface IPlaneControl
      * @exception binder::Status::Exception::EX_ILLEGAL_ARGUMENT for invalid value.
      *
      *
-     * @see getVideoSourceDestinationPlaneMapping()
+     * @see getVideoSourceDestinationPlaneMapping(), getCapture()
      */
     boolean setVideoSourceDestinationPlaneMapping(in SourcePlaneMapping[] listSourcePlaneMapping);
 
@@ -251,5 +259,37 @@ interface IPlaneControl
      * @exception binder::Status::Exception::EX_NULL_POINTER for Null object.
      *
      */
-    @nullable IGraphicsFbProvider getGraphicsFbProvider(in int planeResourceIndex, in IGraphicsFbProviderListener graphicsFbProviderListener); 
+    @nullable IGraphicsFbProvider getGraphicsFbProvider(in int planeResourceIndex, in IGraphicsFbProviderListener graphicsFbProviderListener);
+
+    /**
+     * Gets a Capture interface for a video plane resource.
+     *
+     * A capture plane is a plane whose destination is the client's texture rather than
+     * the display. It routes a video decoder's output into a pool of Dma-Buf buffers
+     * which the client imports as GPU textures. That is a routing decision about where a
+     * decoder's output goes, which is what this interface owns, so a capture destination
+     * is discovered and addressed exactly as a display plane is.
+     *
+     * A capture interface is only available for plane resources of type
+     * `PlaneType.CAPTURE`. A product that supports decode-to-texture declares one capture
+     * plane resource per concurrent capture session it can serve. The method returns
+     * `null` rather than throwing an exception.
+     *
+     * The source captured is the one mapped to this plane through
+     * `setVideoSourceDestinationPlaneMapping()`.
+     *
+     * @param[in] planeResourceIndex        The index of the plane resource.
+     * @param[in] captureEventListener      Listener for capture resource event callbacks.
+     *
+     * @returns A valid capture instance when the plane resource index refers to a plane
+     *          of type `PlaneType.CAPTURE`, or `null` if the plane resource index is
+     *          invalid or the indexed plane is not a capture plane.
+     *
+     * @exception binder::Status::Exception::EX_NONE for success.
+     * @exception binder::Status::Exception::EX_NULL_POINTER for Null object.
+     *
+     *
+     * @see ICapture, ICapture.open()
+     */
+    @nullable ICapture getCapture(in int planeResourceIndex, in ICaptureEventListener captureEventListener);
 }

planecontrol/current/com/rdk/hal/planecontrol/PlaneCapabilities.aidl

@@ -24,6 +24,13 @@ import com.rdk.hal.videodecoder.DynamicRange;
 
 /**
  *  @brief     Plane resource capabilities definition.
+ *
+ *  On a plane of type `PlaneType.CAPTURE` this parcelable carries `planeIndex`,
+ *  `type` and `sourceTypes`. What such a plane delivers - its formats, frame sizes,
+ *  codecs and pool behaviour - is stated in `CaptureCapabilities`.
+ *
+ *  @see CaptureCapabilities, PlaneType.CAPTURE
+ *
  *  @author    Luc Kennedy-Lamb
  *  @author    Peter Stieglitz
  *  @author    Douglas Adler
@@ -35,7 +42,7 @@ parcelable PlaneCapabilities
     /**
      * 0 based index of this plane resource.
      * Video planes shall be listed first, with the primary video plane at resource index 0.
-     * Graphics planes are listed next.
+     * Graphics planes are listed next, followed by capture planes.
      */
     int planeIndex;
 

planecontrol/current/com/rdk/hal/planecontrol/PlaneType.aidl

@@ -20,6 +20,16 @@ package com.rdk.hal.planecontrol;
 
 /**
  *  @brief     Plane type definition.
+ *
+ *  The type says where the plane's pixels come from and where they go, which is what
+ *  determines the interface used to drive it.
+ *
+ *  | Type | Pixels come from | Pixels go to | Interface |
+ *  |---|---|---|---|
+ *  | `VIDEO` | A mapped video source | The display | `IPlaneControl` |
+ *  | `GRAPHICS` | The client, frame by frame | The display | `IGraphicsFbProvider` |
+ *  | `CAPTURE` | A mapped video source | The client, frame by frame | `ICapture` |
+ *
  *  @author    Luc Kennedy-Lamb
  *  @author    Peter Stieglitz
  *  @author    Douglas Adler
@@ -29,13 +39,40 @@ package com.rdk.hal.planecontrol;
 @Backing(type="int")
 enum PlaneType
 {
-    /** 
+    /**
      *  Video plane.
+     *
+     *  Displays a mapped video source. The source is selected with
+     *  `IPlaneControl.setVideoSourceDestinationPlaneMapping()`, and position, size,
+     *  z-order and alpha are set through the plane's `Property` values.
      */
     VIDEO = 0,
- 
-    /** 
+
+    /**
      *  Graphics plane.
+     *
+     *  Displays frames the client draws. `IPlaneControl.getGraphicsFbProvider()`
+     *  provides the frame buffers, and the client creates, commits and destroys them
+     *  through `IGraphicsFbProvider`. Frames travel from the client to the display.
+     */
+    GRAPHICS = 1,
+
+    /**
+     *  Capture plane.
+     *
+     *  Delivers a mapped video source's decoded frames to the client as Dma-Bufs it
+     *  imports as GPU textures. `IPlaneControl.getCapture()` provides the capture
+     *  interface, and the source is selected with
+     *  `IPlaneControl.setVideoSourceDestinationPlaneMapping()` exactly as it is for a
+     *  video plane - the destination is the client's texture instead of the display.
+     *
+     *  What such a plane can deliver, and how its buffer pool behaves, are stated in
+     *  `CaptureCapabilities`. `PlaneCapabilities` carries its routing.
+     *
+     *  It runs in the opposite direction to a graphics plane. Both carry frames between
+     *  the client and the pipeline, but a graphics plane takes frames from the client to
+     *  the display, while a capture plane takes decoded frames from the pipeline to the
+     *  client.
      */
-    GRAPHICS = 1, 
+    CAPTURE = 2
 }

planecontrol/current/com/rdk/hal/planecontrol/SourcePlaneMapping.aidl

@@ -43,6 +43,9 @@ parcelable SourcePlaneMapping
     /**
      * The index of the plane to use as the destination for the video source.
      * A value of -1 indicates no plane.
+     *
+     * A plane of type `PlaneType.CAPTURE` routes the source to the client as Dma-Buf
+     * frames rather than to the display. See `IPlaneControl.getCapture()`.
      */
     int destinationPlaneIndex;
 }

planecontrol/current/com/rdk/hal/planecontrol/capture/CaptureCapabilities.aidl

@@ -0,0 +1,107 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2026 RDK Management
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.rdk.hal.planecontrol.capture;
+
+import com.rdk.hal.planecontrol.capture.FormatLayout;
+import com.rdk.hal.videodecoder.Codec;
+
+/**
+ *  @brief     Capture capabilities definition for a plane resource.
+ *
+ *  Describes what frames this capture plane can deliver and how its buffer pool
+ *  behaves. This is the whole of the capture declaration: a client reads it, selects
+ *  from it through `ICaptureController.setFormat()`, and the vendor layer configures whatever it needs
+ *  to on the decoder to satisfy the selection.
+ *
+ *  @author    Peter Stieglitz
+ *  @author    Gerald Weatherup
+ */
+
+@VintfStability
+parcelable CaptureCapabilities
+{
+    /**
+     * Indicates the behaviour when every buffer in the pool is locked by the client and
+     * the decoder has a new frame to write.
+     *
+     * When true, the decoder stalls until a buffer is released.
+     * When false, the oldest Ready buffer is recycled and its frame is dropped.
+     * Decode proceeds at full rate in both cases for as long as buffers are available.
+     */
+    boolean stallsWhenPoolExhausted;
+
+    /**
+     * The pixel format and memory layout pairs this capture plane can deliver.
+     *
+     * Paired, because a modifier is not valid with every format: most modifiers are
+     * vendor-namespaced tiling or compression layouts that apply to particular
+     * formats and bit depths. Declaring two independent lists would offer a client
+     * the full cross-product, most of which a plane cannot deliver, and leave it to
+     * find out at `start()`.
+     *
+     * A client selects one entry and passes it to
+     * `ICaptureController.setFormat()`.
+     *
+     * These are the pairs this product can deliver, and the whole of them. A client
+     * that can handle none of them cannot capture from this plane.
+     */
+    FormatLayout[] supportedFormats;
+
+    /**
+     * The maximum frame width in pixels this capture plane can deliver.
+     *
+     * @see Property.WIDTH
+     */
+    int maxFrameWidth;
+
+    /**
+     * The maximum frame height in pixels this capture plane can deliver.
+     *
+     * @see Property.HEIGHT
+     */
+    int maxFrameHeight;
+
+    /**
+     * The video codecs whose decoded frames this plane can capture.
+     *
+     * Capture is not required of every codec a platform can decode. A decoder opened
+     * for a codec outside this list decodes and displays normally; what it cannot do is
+     * feed a capture plane.
+     *
+     * @see com.rdk.hal.videodecoder.Codec
+     */
+    Codec[] supportedCodecs;
+
+    /**
+     * Whether this plane can deliver frames at a resolution other than the one the
+     * mapped source is decoding.
+     *
+     * When false, the plane's `Property.WIDTH` and `HEIGHT` must equal the resolution the
+     * mapped source decodes to, and `ICaptureController.start()` fails with
+     * `CaptureErrorCode.RESOLUTION_MISMATCH` if they do not. Nothing is scaled: the
+     * frames the client receives are the frames the decoder produced.
+     *
+     * Declaring false is what keeps the tested surface small - a plane that never
+     * scales has no scaling quality to validate and no resolution permutations to
+     * cover.
+     *
+     * @see Property.WIDTH, Property.HEIGHT, CaptureErrorCode.RESOLUTION_MISMATCH
+     */
+    boolean resize;
+}

planecontrol/current/com/rdk/hal/planecontrol/capture/CaptureErrorCode.aidl

@@ -0,0 +1,79 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2026 RDK Management
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.rdk.hal.planecontrol.capture;
+
+/**
+ *  @brief     Capture error code definitions.
+ *  @author    Peter Stieglitz
+ *  @author    Gerald Weatherup
+ */
+
+@VintfStability
+@Backing(type="int")
+enum CaptureErrorCode {
+
+    /** The platform refused the buffer pool reservation from the video memory region. */
+    OUT_OF_MEMORY = 1,
+
+    /**
+     * No video source is mapped to this capture plane.
+     *
+     * @see IPlaneControl.setVideoSourceDestinationPlaneMapping()
+     */
+    SOURCE_NOT_MAPPED = 2,
+
+    /**
+     * The mapped source is decoding a codec this plane cannot capture.
+     *
+     * @see CaptureCapabilities.supportedCodecs
+     */
+    CODEC_NOT_CAPTURABLE = 3,
+
+    /** An unrecoverable hardware fault occurred, such as an IOMMU fault. */
+    HARDWARE_FAULT = 4,
+
+    /**
+     * The configured capture resolution does not match the resolution the mapped
+     * source is decoding, on a plane that cannot resize.
+     *
+     * @see CaptureCapabilities.resize, Property.WIDTH, Property.HEIGHT
+     */
+    RESOLUTION_MISMATCH = 5,
+
+    /**
+     * The colour conversion the configured format would require of the mapped source
+     * is not one this plane can perform.
+     */
+    COLOR_CONVERSION_UNSUPPORTED = 6,
+
+    /**
+     * The configured pixel format or memory layout cannot be delivered for the mapped
+     * source, even though the plane declares it.
+     *
+     * @see CaptureCapabilities.supportedFormats, ICaptureController.setFormat()
+     */
+    FORMAT_UNSUPPORTED = 7,
+
+    /**
+     * The session's configuration is not a combination this plane can deliver, or is
+     * incomplete - `start()` raises this where no format was selected with
+     * `ICaptureController.setFormat()`.
+     */
+    INVALID_CONFIGURATION = 8,
+}