#
# Copyright (c) 2017-2020, NVIDIA CORPORATION. All rights reserved.
#
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the "Software"),
# to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.
#

************************************************************************
                               Linux for Tegra
                               Graphics Samples
                                   README
************************************************************************


The following samples are provided for X11, Wayland and EGLDevice
windowing system.

 - gears-basic
 - gears-cube
 - bubble
 - ctree
 - eglstreamcube

Apart from these samples there are a few supporting libraries like nvtexfont,
nvgldemo and gears-lib.


To cross-compile these samples on Linux Host for aarch64 target
-------------------------------------------------------------------------
1. Ensure that the cross-compilation toolchain, corresponding platform header,
   and rootfs of the target are available on the host system.
2. Export the environment variables and ensure the PATH variable
   contains the path of the cross-compilation toolchain.

Command Steps:
    1) export TOOLCHAIN_PREFIX="aarch64-unknown-linux-gnu-"
    2) export PATH=$PATH:path_to_toolchain, i.e., ensure that PATH variable contains
       path of cross-compilation toolchain
    3) export ROOTFS=path to rootfs

A) For Linux X11 platform:
    export X11_INC=path to X11 headers
    export NV_WINSYS=x11

B) For Linux Wayland platform:
    export WAYLAND_INC=path to Wayland includes
    export XKBCOMMON_INC=path to xcbcommon headers
    export NV_WINSYS=wayland

c) For Linux EGLDevice platform:
   export NV_WINSYS=egldevice

WAR to known issue/problem:
Problem: standard libraries (libc, libpthread, etc.) are present under both
         ${TARGET_ROOTFS}/usr/lib/aarch64-linux-gnu/ &
         ${TARGET_ROOTFS}/lib/aarch64-linux-gnu/

Error signature due to above:
${CROSS_COMPILATION_PATH}/tools/linux/nvidia/aarch64-unknown-linux-gnu/gcc-4.8.5-glibc-2.17-static/bin/../lib/gcc/aarch64-unknown-linux-gnu/4.8.5/../../../../aarch64-unknown-linux-gnu/bin/ld: cannot find /lib/aarch64-linux-gnu/libpthread.so.0
${CROSS_COMPILATION_PATH}/tools/linux/nvidia/aarch64-unknown-linux-gnu/gcc-4.8.5-glibc-2.17-static/bin/../lib/gcc/aarch64-unknown-linux-gnu/4.8.5/../../../../aarch64-unknown-linux-gnu/bin/ld: cannot find /usr/lib/aarch64-linux-gnu/libpthread_nonshared.a
collect2: error: ld returned 1 exit status

Solution: Remove libraries from ${TARGET_ROOTFS}/usr/lib/aarch64-linux-gnu/

To build any of the samples:
-------------------------------------------------------------------------
1. Navigate to the directory where the sample is located.
   cd graphics_demos/<sample_name>

Where <sample_name> is the name of the sample you are building.

2. Execute the command.
   make clean
   make

When the build is successful, the sample binary will be generated in the
respective (X11,Wayland,EGLDevice) folder within samples folder.
The prebuilt binaries are also available in graphics_demos/prebuilts/bin.

To run the samples:
-------------------------------------------------------------------------
- Copy the binary from the respective sub folder to the target and run.

To compile these samples on target device:
-------------------------------------------------------------------------
- Install the dependencies for these samples:
   sudo apt-get update
   sudo apt-get install gcc g++ make

A) For Linux X11 platform:
   sudo apt-get install libx11-dev

B) For Linux Wayland platform:
   sudo apt-get install libxkbcommon-dev
   sudo apt-get install libwayland-dev

c) For Linux EGLDevice platform:
   sudo apt-get install libdrm-dev

To build the samples, for example gears-cube:
-------------------------------------------------------------------------
A) For Linux X11 platform:
    export X11_INC=path to X11 headers
    export NV_WINSYS=x11

B) For Linux Wayland platform:
    export WAYLAND_INC=path to Wayland includes
    export XKBCOMMON_INC=path to xcbcommon headers
    export NV_WINSYS=wayland

c) For Linux EGLDevice platform:
   export NV_WINSYS=egldevice
   export DRM_INC=path to drm header

cd $HOME/graphics_demos
cd gears-cube
make clean
make

Upon successful execution, the sample binary is generated in the
respective folder (X11,Wayland,EGLDevice) within the <sample_name> directory.

Where <sample_name> is the name of the sample you are building.

Instructions for running the samples is provided in the README within the
<sample_name> directory. Additionally, complete instructions are provided
in the documentation.
-------------------------------------------------------------------------

To build samples with IVI shell support:
---------------------------------------
Note: These are compiled on the target platform.

1) Install the following packages:
     sudo apt install libwayland-dev libgbm-dev libdrm-dev \
                      libegl1-mesa-dev libgles2-mesa-dev libxkbcommon-dev

2) Enable IVI shell support in code:

   In Makefile.l4tsdkdefs, add this line:
     NV_PLATFORM_CPPFLAGS += -DENABLE_IVI_SHELL

   in the common code. This will enable building of samples with IVI shell.

3) Download wayland-ivi-extensions:

   Let the sources be cloned into ivi-ext folder:
     mkdir ivi-ext

   Download the Wayland IVI extensions from
   https://github.com/GENIVI/wayland-ivi-extension and checkout 2.2.0
     git clone https://github.com/GENIVI/wayland-ivi-extension
     git checkout 2.2.0

4) Generate header and source with wayland-scanner:
     wayland-scanner public-code ./ivi-ext/wayland-ivi-extension/protocol/ivi-application.xml /usr/include/ivi-application-interface.c
     wayland-scanner client-header ./ivi-ext/wayland-ivi-extension/protocol/ivi-application.xml /usr/include/ivi-application-client-protocol.h

5) Copy headers:
     cp -r ivi-ext/wayland-ivi-extension/ivi-layermanagement-api/ilmCommon/include/* /usr/include/
     cp -r ivi-ext/wayland-ivi-extension/ivi-layermanagement-api/ilmClient/include/* /usr/include/
     cp -r ivi-ext/wayland-ivi-extension/ivi-layermanagement-api/ilmControl/include/* /usr/include/

6) In Makefile.l4tsdkdefs extend the NV_PLATFORM_WINSYS_LIBS list with "-l:libilmClient.so.2.2.0"

7) Go to the bubble folder, and build
     NV_WINSYS=wayland make clean && make
   This will build the sample with IVI shell support
