.. _edgematic_simaai_decoder:


simaaidecoder
=============

Description
+++++++++++

:menuselection:`Catalog --> PLUGINS --> SiMa Plugins --> hardware_plugins`

:menuselection:`Catalog --> PLUGINS --> Plugin Group --> ethernet_output`

**GStreamer plugin reference**: :ref:`plugin_simaaidecoder`

The |plugin_highlighted| GStreamer plugin is a video decoder that supports H.264 and H.265 decoding.
It integrates with SiMa.ai hardware for efficient video processing. The plugin outputs video frames
in either NV12 or YUV420P format.

.. image:: media/plugin_simaaidecoder_hover_name.png
    :scale: 80%
    :align: center
|

Plugin Configurations
+++++++++++++++++++++

All plugins in Edgematic have options and configurations that can be accessed via:

#. The configuration icon on the top right of each plugin (|plugin_config_button|).
#. The source code found in :menuselection:`Explorer --> SOURCE --> plugins`.

Plugin configuration options
****************************

The plugin configurator provides 3 tabs:

* :guilabel:`GENERAL`: Generic configuration options shared among plugins. Usually contains mostly which processor this
  plugin is executing on. In this case, it should state ``APU``.
* :guilabel:`CONFIGURATION`: This is where the configurations for ``input_buffers`` block and ``output_memory_order`` 
  block could be set/reviewed.
* :guilabel:`ADVANCED`: 

    * ``Custom meta for o/p buffer (Optional)``
        * Sets a custom string as metadata for the output buffer. This is used to tag the output buffer with a specific
          name, which can be useful for downstream processing or buffer identification. If not specified, it defaults
          to the node name from the configuration, or the element name if no node name is provided.
        * ``String``. Default: ``simaaidecoder0``
    * ``1 - no segment API, 2 - segment API support (Optional)``
        * Controls whether the decoder operates with or without segment API support. When set to 1, the decoder does not
          use the segment API (default legacy mode). When set to 2, the decoder enables segment API support, which
          allows for advanced features.
        * ``Integer``. Default: ``1``
    * ``ip-queue-max-buffers (Optional)``
        * Sets the high water mark for the input buffer queue. If the number of input buffers in the queue exceeds this
          value, the decoder will block and stop accepting new input buffers until the queue size drops below this
          threshold. This helps manage memory usage and flow control in the pipeline.
        * ``Integer``. Default: ``60``
    * ``ip-queue-min-buffers (Optional)``
        * Sets the low water mark for the input buffer queue. If the number of input buffers in the queue drops below
          this value, the decoder may pause processing or wait for more input buffers to arrive before resuming. This
          helps manage flow control and ensures the decoder has enough data to operate efficiently.
        * ``Integer``. Default: ``30``
    * ``memory-opt (Optional)``
        * Enables or disables memory optimization for the decoder. When set to true, the decoder will use optimized
          memory allocation strategies to reduce memory usage and improve performance, especially in multi-stream or
          resource-constrained scenarios. This may involve using smaller or more efficient buffer pools, or leveraging
          hardware-specific memory features.
        * ``Boolean``. Default: ``false``
    * ``Decoder width (Optional)``
        * Specifies the width (in pixels) of the video frames to be decoded. This parameter tells the decoder the
          expected horizontal resolution of the input video stream.
        * ``Integer``. Range: ``0 - 1920`` Default: ``-1``
    * ``Decoder height (Optional)``
        * Specifies the height (in pixels) of the video frames to be decoded. This parameter tells the decoder the
          expected vertical resolution of the input video stream.
        * ``Integer``. Range: ``0 - 1080`` Default: ``-1``
    * ``Next element (Optional)``
        * Choose one of o/p pool "CVU","FPGA","ISP" "APU" (as of now only CVU & APU supported)
        * String. Default: "CVU"
    * ``Specify if op-buff from decoder is cached (applicable for CVU & CMA heap) (Optional)``
        * Specifies whether the output buffer (op-buff) allocated by the decoder should be cached. This setting is
          relevant when using the CVU (Computer Vision Unit) or CMA (Contiguous Memory Allocator) heap types. 

            * When set to true, the output buffer is cached, which can improve CPU access performance but may require
              explicit cache management (flush/invalidate) for hardware coherency. 
            * When set to false, the output buffer is non-cached,  which avoids cache coherency issues but may result
              in slower CPU access.
        * ``Boolean``. Default: ``false``
    * ``When TRUE, any resolution change is dropped immediately (Optional)``
        * Controls how the decoder handles resolution changes in the input stream.

          * When set to true, the decoder will immediately drop (ignore) any frames that signal a resolution change,
            maintaining the original resolution throughout the session.
          * When set to false, the decoder will attempt to handle resolution changes dynamically, which may involve
            reconfiguring buffers and internal state.
        * This is useful in scenarios where dynamic resolution changes are not supported or not desired, ensuring
          consistent output resolution and avoiding pipeline disruptions.

Plugin source configurations (advanced)
***************************************

If you wish to directly alter the code or configurations for the plugin, simply click on the plugin on the canvas and
the source will be highlighted in orange on the left :menuselection:`Explorer --> SOURCE` panel.

.. |plugin| replace:: simaaiencoder
.. |plugin_highlighted| replace:: ``simaaiencoder``
.. |plugin_config_button| image:: media/plugin_config_button.png
   :width: 25px
   :height: 25px