docs(linux): Add documentation regaring DSS feature: cropping

This documentation includes examples showing the cropped part of a frame.

Signed-off-by: Swamil Jain <[email protected]>

Author: s-jain1

source/images/DSS_cropping_example_1.jpg

@@ -490,8 +490,8 @@ tidss supports configuration via DRM properties. These are standard DRM properti
 | GAMMA_LUT_SIZE     | crtc     | Number of elements in gammma lookup table.                                                           |
 +--------------------+----------+------------------------------------------------------------------------------------------------------+
 
-Testing tidss properties with modetest
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Testing tidss properties with modetest and kmstest
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 As the name suggests, ``modetest`` is DRM based mode setting test program available along with libdrm.
 It is an easy-to-use tool to test different features provided by display HWs. The DRM driver for,
@@ -663,6 +663,59 @@ The following example was run on DSS7-UL and hence the pipe with scaling capabil
 
 Note that the ``*2`` at the end of ``-P 41@38:400x400*2`` is the scaling factor.
 
+- **Cropping**
+
+Show only a part of the frame.
+
+User can specify a frame of size ``w x h``, with an input color format ``cf``, a view ``w1 x h1`` starting at coordinates ``x1,y1`` and a plane ``w2 x h2`` to be displayed starting at coordinates ``x2,y2``. To display a cropped part of the frame(``w x h``), the below command can be used:
+
+.. code-block:: console
+
+   $ kmstest -p <plane_number>:<x-coordinate>,<ycoordinate>-<plane_width>x<plane_height> -f <frame_width>x<frame_height>-<color-format> -v <view_number>:<x-coordinate>,<ycoordinate>-<view_width>x<view_height>
+
+   $ kmstest -p 0:x2,y2-w2xh2 -f wxh-cf -v x1,y1-w1xh1
+
+.. code-block:: console
+
+   $ kmstest -c hdmi -p 0:0,0-1000x1000 -f 1000x1000-XR24 -v 0,0-1000x1000
+   Connector 1/@50: HDMI-A-1
+   Crtc 1/@48: [email protected] 138.500 1920/48/32/80/+ 1080/3/5/23/- 60 (59.93) 0x9 0x48
+   Plane 0/@31: 0,0-800x800
+   Fb 55 1000x1000-XR24
+
+The above example views a ``1000x1000`` frame on a ``1000x1000`` plane starting at ``0,0``.
+
+.. figure:: /images/DSS_cropping_example_1.jpg
+   :height: 600
+   :width: 1020
+
+.. code-block:: console
+
+   $ kmstest -c hdmi -p 0:0,0-800x800 -f 1000x1000 -v 0,0-800x800
+   Connector 1/@50: HDMI-A-1
+   Crtc 1/@48: [email protected] 138.500 1920/48/32/80/+ 1080/3/5/23/- 60 (59.93) 0x9 0x48
+   Plane 0/@31: 0,0-400x400
+   Fb 55 1000x1000-XR24
+
+The first example shows the whole ``800x800`` frame and second example shows cropped part ``(400x400)`` of the ``800x800`` frame.
+
+.. figure:: /images/DSS_cropping_example_2.jpg
+   :height: 600
+   :width: 1020
+
+.. code-block:: console
+
+   $ kmstest -c hdmi -p 0:500,200-800x800 -f 1000x1000 -v 200,100-800x800                                                                                                                     
+   Connector 1/@50: HDMI-A-1
+   Crtc 1/@48: [email protected] 138.500 1920/48/32/80/+ 1080/3/5/23/- 60 (59.93) 0x9 0x48
+   Plane 0/@31: 500,200-800x800
+   Fb 54 1000x1000-XR24
+
+This example views the ``800x800`` cropped part of the frame starting at ``200,100`` on a ``800x800`` plane starting at ``500,200``.  
+
+.. figure:: /images/DSS_cropping_example_3.jpg
+   :height: 600
+   :width: 1020
 
 Buffers
 -------