fix(graphics): follow almost all vale suggestions

Follow almost every vale suggestion.

Signed-off-by: Randolph Sapp <rs@ti.com>

Author: StaticRocket

source/linux/Foundational_Components/Graphics/Common/Display.rst

@@ -2,29 +2,28 @@
 Display
 #######
 
-TI SoCs are equipped with Display SubSystem (DSS) hardware to provide hardware
-acceleration for alpha blending of overlays and color conversion. The DSS
-hardware is exposed to the software drm API available through ``libdrm`` module.
-Through this drm interface, a user space program can perform *mode setting* of
-the display.
+TI SoCs with Display Sub-System (DSS) hardware offer hardware acceleration for
+alpha blending of overlays and color conversion. The ``libdrm`` module exposes
+DSS hardware through the software Direct Render Management (DRM) API. Through
+this DRM interface, a user space program can perform *mode setting* of the
+display.
 
-The drm module models the display hardware as a series of abstract hardware
+The DRM module models the display hardware as a series of abstract hardware
 blocks and manages them through the API. The blocks are:
 
    - CRTC\ [#f1]_\: represents a scanout engine that generates video timing
      signal from the data pointed to by the scanout buffer
 
-   - Connector: represents where the video timing signal is sent across to the
-     display
+   - Connector: represents where the video timing signal goes and how it gets
+     there
 
-   - Encoder: transforms the video timing signal from CRTC to a format that is
-     suitable for sending across the connector
+   - Encoder: transforms the video timing signal from the CRTC to a format that
+     is suitable for sending to the connector
 
-   - Plane: represents the overlay buffer that a CRTC can be fed with
+   - Plane: represents the overlay buffer that will feed a CRTC
 
-A utility application ``modetest`` can be used to get the list of available drm
-blocks. All the information available for the device can be displayed by using
-it.
+The list of available DRM blocks is viewable using the application
+:command:`modetest`.
 
 .. ifconfig:: CONFIG_image_type in ('adas')
 
@@ -37,11 +36,13 @@ it.
        linux-dtbs and install. Also need to disable Display in r5f, rebuild
        r5f FW using PSDK RTOS.
 
-********************
-Finding Connector ID
-********************
+.. _finding_the_connector_id:
 
-Run the below ``modetest`` command:
+************************
+Finding the connector ID
+************************
+
+Run the following ``modetest`` command:
 
 .. ifconfig:: CONFIG_part_family in ('General_family', 'AM335X_family', 'AM437X_family')
 
@@ -55,8 +56,8 @@ Run the below ``modetest`` command:
 
       # modetest -M tidss -c
 
-Look for the display device for which the connector ID is required -
-such as HDMI, LCD etc.
+Look for the required display device's connector ID - such as High-Definition
+Multimedia Interface (HDMI), DisplayPort (DP), and so on.
 
 .. code-block:: text
 
@@ -75,9 +76,9 @@ such as HDMI, LCD etc.
 The modes displayed are the various resolutions supported by the connected
 display.
 
-****************
-Finding Plane ID
-****************
+********************
+Finding the plane ID
+********************
 
 To find the Plane ID, run the ``modetest`` command:
 
@@ -93,7 +94,7 @@ To find the Plane ID, run the ``modetest`` command:
 
       # modetest -M tidss -p
 
-Which should show something like below:
+Which should show something similar to the following:
 
 .. code-block:: text
 
@@ -108,43 +109,44 @@ Which should show something like below:
     props:
     ...
 
-*******************************
-Using Connector ID and Plane ID
-*******************************
+***********************************
+Using the connector ID and plane ID
+***********************************
 
-The above information may be used with some userspace applications to control
-which displays are rendered to. These applications are using what is known as
-kernel mode setting (kms). For more information about kernel mode setting see
-the `upstream kms documentation`_. In this section you only need to keep 2
-things in mind:
+The earlier information is useful when attempting to select what display to
+render to. Some user space applications have command line switches to easily
+show this. These applications are using Kernel Mode Setting (KMS). For more
+information about KMS see the `upstream kms documentation`_. For now, you only
+need to keep 2 things in mind:
 
-   #. Applications that intend to interact with the kms interface usually don't
-      need any user input. They can query device info through the interface and
-      will normally pick the first connected display automatically.
+   #. Applications that intend to interact with the KMS interface usually do not
+      need any user input. They can query device info through the interface
+      and will normally pick the first connected display automatically.
 
-   #. Only one application can manage the kms interface at a time. Weston is
-      normally the first graphical application started out of the box and as
-      such it will prevent you from starting any other kms applications. See
-      :ref:`stopping-weston` if you want to use another kms application.
+   #. Only one application can manage the KMS interface at a time. Weston is
+      normally the first graphical application started by default and as such
+      it will prevent you from starting any other KMS applications. See
+      :ref:`stopping-weston` if you want to use another KMS application.
 
 .. _upstream kms documentation: https://www.kernel.org/doc/html/latest/gpu/drm-kms.html
 
-That being said, if you wish to change rendering behavior for an application
-check with that applications documentation for a way to specify connector,
-plane, and / or crtc information. One kms application we include is ``kmscube``.
-Below are some examples on how to alter it's default behavior.
+If you want to change rendering behavior for an application check with that
+applications documentation for a way to specify a connector, plane, and / or
+CRTC information. One KMS application we include is :command:`kmscube`. Below
+are some examples on how to avoid the default behavior of automatically choosing
+a display to render to.
 
-Run kmscube on the default display:
+Run :command:`kmscube` on the default display:
 
 .. code-block:: console
 
    # kmscube
 
-Run kmscube on the secondary display:
+Run :command:`kmscube` on the secondary display:
 
 .. code-block:: console
 
-   # kmscube -n <connector-id>
+   # kmscube -n <connector_id>
 
 For example, if the connector id for the secondary display is 16:
 
@@ -154,7 +156,7 @@ For example, if the connector id for the secondary display is 16:
 
 .. [#f1]
 
-   CRTC stands for cathode-ray tube controller, a throw back to the old
+   CRTC stands for Cathode-Ray Tube Controller, a throw back to the old
    `cathode-ray tubes TV's <https://en.wikipedia.org/wiki/Cathode-ray_tube>`_
    which had a controller that generated video timings based on the data it is
-   being fed by a buffer.
+   receiving from a buffer.

source/linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework.rst

@@ -2,14 +2,14 @@
     This subsection provides details on the GTK+ graphics frameworks
 
 #######################
-GTK+ Graphics Framework
+GTK+ graphics framework
 #######################
 
 GTK+, or the GIMP Toolkit, is a multi-platform toolkit for creating graphical
-user interfaces.  Offering a complete set of widgets, GTK+ is suitable for
+user interfaces. Offering a complete set of widgets, GTK+ is suitable for
 projects ranging from small one-off tools to complete application suites.
 
-Please refer to `<https://www.gtk.org/>`_ for additional details on GTK+.
+See `<https://www.gtk.org/>`_ for additional details on GTK+.
 
 The PSDK target file system includes the pre-built GTK+ libraries under
 :file:`/usr/lib` for GTK+3 over Wayland support. There is also a comprehensive
@@ -20,15 +20,14 @@ APIs and their usages.
 Demos
 *****
 
-GTK+ will attempt to interact with a windowing system on startup. If one is not
-running, or it fails to connect to one for any reason, you will see the
-following error:
+GTK+ will interact with a windowing system on startup. If one is not running, or
+it fails to connect to one for any reason, you will see the following error:
 
 .. code-block:: text
 
-   (<application-name>:<pid>): Gtk-WARNING **: 21:21:27.361: cannot open display: <display>
+   (<application_name>:<pid>): Gtk-WARNING **: 21:21:27.361: cannot open display: <display>
 
-If no display value is returned, then you are more than likely missing the
-``WAYLAND_DISPLAY`` environment variable. Check the :doc:`Weston`
-section for more information.
+If no display value is present, then you are more than likely missing the
+``WAYLAND_DISPLAY`` environment variable. Check the :doc:`Weston` section for
+more information.
 

source/linux/Foundational_Components/Graphics/Common/OpenCL.rst

@@ -4,11 +4,11 @@
 OpenCL
 ######
 
-The OpenCL\ |trade| libraries are packaged with the |__SDK_FULL_NAME__| and are
-used by compute centric libraries for offloading tasks to the GPU without the
-overhead of managing displays or creating a offscreen context. The drivers run
-on an ARM core and programs the firmware running inside a GPU core with commands
-submitted by the user applications.
+The OpenCL\ |trade| libraries in the |__SDK_FULL_NAME__| allow offloading tasks
+to the GPU for compute centric libraries without the GPU or CPU usage incurred
+by managing displays or creating a offscreen context. The drivers run on an ARM
+core and programs the firmware running inside a GPU core with commands submitted
+by the user applications.
 
 OpenCL\ |trade| differs from OpenGL\ |reg| in that it makes use of a predefined
 Installable Client Driver (ICD) Loader to allow applications to query and pick
@@ -19,16 +19,15 @@ an ICD loader library instead of directly using a specific library.
 
 .. note::
 
-   Tools may choose to dynamically load their respective OpenCL\ |trade| library
-   at runtime using dlopen, which may fail in Yocto based environments. This is
+   Some tools dynamically load their respective OpenCL\ |trade| library at
+   runtime by using dlopen, which can fail in Yocto based environments. This is
    usually the result of a clash in philosophies between Yocto and Application
-   developers over the usage of devlinks (also know in Yocto as "dev-so"s). It's
-   Yocto's belief that, for the most part, applications should not attempt to
-   use dev links directly and should instead open the specific version of the
-   library they need. You may choose to patch the application to do this or
-   create the devlink from :file:`/usr/lib/libOpenCL.so` to
-   :file:`/usr/lib/libOpenCL.so.1` manually. Tools provided by Yocto will be
-   patched accordingly already.
+   developers over the usage of devlinks (also know in Yocto as "dev-so"s). It
+   is Yocto's belief that, for the most part, applications should not try to use
+   dev links directly and should instead open the specific version of the
+   library they need. You can patch the application to do this or create the
+   devlink from :file:`/usr/lib/libOpenCL.so` to :file:`/usr/lib/libOpenCL.so.1`
+   manually. Tools provided by Yocto will are already patched.
 
 A useful tool for debugging OpenCL\ |trade| ICD Loaders and devices is
 :command:`clinfo`. This command, when run without any arguments will present a

source/linux/Foundational_Components/Graphics/Common/OpenGL_ES.rst

@@ -4,10 +4,11 @@
 OpenGL ES
 #########
 
-The OpenGL\ |reg| ES and EGL\ |reg| libraries are packaged with the
-|__SDK_FULL_NAME__| and are used by graphics stacks such as Wayland/Weston. The
-drivers run on an ARM core and programs the firmware running inside a GPU core
-with rendering commands submitted by the user applications.
+The OpenGL\ |reg| ES and EGL\ |reg| libraries packaged with the
+|__SDK_FULL_NAME__| used by graphics stacks such as Wayland/Weston provide
+accelerated rendering capabilities. The drivers run on an ARM core and program
+the firmware running inside a GPU core with rendering commands submitted by the
+user applications.
 
 For more information about OpenGL\ |reg| ES and EGL\ |reg| extensions see:
 

source/linux/Foundational_Components/Graphics/Common/PVR_Tools.rst

@@ -1,38 +1,35 @@
 .. include:: <isonum.txt>
 
 #############
-PowerVR Tools
+PowerVR tools
 #############
 
-The suite of PowerVR Tools is designed to enable rapid graphics application
-development. It targets a range of areas including asset exporting and
-optimization, PC emulation, prototyping environments, on-line and off-line
-performance analysis tools and many more. Please refer to PowerVR-SDK_ for
-additional details on the tools and detailed documentation.
+The suite of PowerVR Tools exist to help enable rapid graphics application
+development. They target a range of areas including asset exporting and
+optimization, PC emulation, prototyping environments, online and offline
+performance analysis tools and many more. See PowerVR-SDK_ for additional
+details on the tools and detailed documentation.
 
-There are a number of useful tools available in the Imagination PowerVR SDK that
-are compatible with our devices. Two of the most useful tools available are
-PVRTune and PVRCarbon, which can be used for to profiling and tracing GFX
-activities.
+There are several useful tools available in the Imagination PowerVR SDK that are
+compatible with our devices. Two of the most useful tools available are PVRTune
+and PVRCarbon, which enable profiling and tracing of Graphics (GFX) activities.
 
-Previously these were included in the target's rootfs, but these were removed
-due to tight version dependencies between the target and host tools. Imagination
-has moved to packaging the target binaries with their host installer, so we
-recommend using those binaries directly for guaranteed compatibility.
+Imagination has moved to packaging the target binaries with their host
+installer, so we recommend using those binaries directly for guaranteed
+compatibility.
 
 *******
 PVRTune
 *******
 
 The PVRTune utility is a real-time GPU performance analysis tool. It captures
-hardware timing data and counters which facilitate the identification of
-performance bottlenecks. PVRPerfServer should be used along with the PVRTune
-running on the PC to gather data on the SGX loading and activity threads. The
-target binaries can be found in the host's PVRTune installation directory under
-PVRPerfServer.
+hardware timing data and counters that ease the identification of performance
+bottlenecks. PVRPerfServer collects data that is displayed with the PVRTune
+running on the PC. The target binaries reside in the host's PVRTune installation
+directory under :file:`PVRPerfServer`.
 
-For more information please refer to Imagination's upstream documentation on
-PVRTune and PVRPerfServer.
+For more information see Imagination's upstream documentation on PVRTune and
+PVRPerfServer.
 
    - `<https://docs.imgtec.com/tools-manuals/pvrtune-manual/html/pvrtune-manual/topics/introduction.html>`_
 
@@ -43,11 +40,11 @@ PVRCarbon
 The PVRCarbon is an OpenGL\ |reg| ES and Vulkan |reg| API recording and analysis
 utility. PVRCarbon GUI provides off-line tools to inspect captured data,
 identify redundant calls, highlight costly shaders and many more. This tool can
-capture traces on target and then play them back on multiple different devices
-by introducing shim libraries in place of the standard offering for that API.
+capture traces on target and then play them back on different devices by
+introducing shim libraries in place of the standard offering for that API.
 
-This requires a little bit of setup on the target though. Please refer to
-Imagination's upstream target setup guide for the most recent instructions.
+This requires a little bit of setup on the target though. See Imagination's
+upstream target setup guide for the most recent instructions.
 
    - `<https://docs.imgtec.com/tools-manuals/pvrcarbon-manual/html/topics/pvrcarbon-recorder/opengl-es.html>`_