Sample Applications

This topic contains information about several sample applications that are provided with NVIDIA® Jetson™ Linux.

NVIDIA Graphics Sample Applications

NVIDIA graphics samples are included in Jetson Linux. This topic gives detailed steps for building and running these samples on the target.

Building the Samples

The sample source files are available in the directory /usr/src/nvidia/graphics_demos. The samples currently provided are:

  • gears-basic

  • gears-cube

  • bubble

  • ctree

  • eglstreamcube

The sample applications may be built on either the host or the target. The file /usr/src/nvidia/graphics_demos/README contains instructions for building the sample applications on either system.

Jetson Linux also provides pre-built binaries for all of the sample applications under all three supported graphics systems. The pre-built binaries are at /usr/src/nvidia/graphics_demos/bin.

Starting the Graphics System

This section describes the procedure for starting your preferred graphics system as a prerequisite for running sample applications.

X11 (X Window System)

Before you can run X11 graphics sample applications you must start the X server in the background. You must also export the DISPLAY variable, which the X driver uses to launch sample applications on the selected display.

  1. Enter these commands to export the DISPLAY environment variable and start the X server:

    $ export DISPLAY=:0
    $ xinit &
    
  2. After you start the X server, open a terminal window (i.e. launch an instance of xterm).

Wayland

Before you can run the Wayland graphics sample applications, you must first stop the X server (which is running by default) and then launch Weston. There are two ways to launch Weston, described in the following subsections.

To launch Weston with a script

  • Enter this command to launch Weston:

    $ nvstart-weston.sh
    

    The script may ask for your password to run some preliminary steps, such as modprobing the display driver and adding your username to proper group. It may also ask you to reboot after a fresh flash of BSP.

    Note

    This script launches Weston with desktop-shell, without any additional options. If you want to run a different shell or use options, such as --modules, you must use the manual procedure described in the next section.

To launch Weston manually

  1. If the X server is running, stop it:

    $ sudo service gdm stop; sudo pkill -9 Xorg
    
  2. For an NVIDIA® Jetson AGX Orin™ device, start the nvidia-drm driver:

    $ sudo modprobe nvidia-drm modeset=1
    

    For an NVIDIA® Jetson AGX Xavier™ or NVIDIA Jetson Xavier™ NX series device, start the Tegra dummy DRM driver:

    $ sudo modprobe tegra-udrm modeset=1
    
  3. Create a libgbm.so.1 symlink:

    $ sudo ln -sf /usr/lib/aarch64-linux-gnu/tegra/libnvgbm.so /usr/lib/aarch64-linux-gnu/libgbm.so.1
    
  4. Set up the environment and directory permissions:

    $ unset DISPLAY
    $ mkdir /tmp/xdg
    $ chmod 700 /tmp/xdg
    
  5. Choose a valid TTY device:

    $ export WESTON_TTY=1
    
  6. Launch Weston.

    • To launch Weston as a root user, enter this command:

      $ sudo XDG_RUNTIME_DIR=/tmp/xdg weston --tty="$WESTON_TTY" --idle-time=0 &
      

      Optional: Set the environment variable WAYLAND_DEBUG to server to dump protocol messages from the server to stderr:

      $ WAYLAND_DEBUG=server
      

      Optional: Use the --use-egldevice switch to disable GBM swapchains and use EGLStream to write Weston output.

    • To launch Weston as a non-root user with weston-launch, enter these commands:

      $ sudo groupadd weston-launch
      $ sudo usermod -a -G weston-launch $USER
      $ sudo chown root /usr/bin/weston-launch
      $ sudo chmod +s /usr/bin/weston-launch
      $ weston-launch &
      

EGLDevice

Before you can run EGLDevice graphics sample applications you must ensure that no display server or compositor is running, since EGLDevice applications are started by default on the default CRTC plane and communicate directly with the display using EGLOutput Ext. For more information, see the Khronos man page for EXT_stream_consumer_egloutput.

If you want to start sample applications on an overlay plane, use the sample applications’ -layer option.

Running the Sample Applications

To run a sample built on the target, run the sample from the appropriate subdirectory of the samples directory for your chosen graphics system.

For example, to run the pre-built version of gears:

$ cd /usr/src/nvidia/graphics_demos/prebuilts/bin/<graphics>
$ ./bubble

Where <graphics> is x11, wayland, or egldevice.

The sample application presents a rendered screen on the display and prints a run log on the terminal that shows the display rate in frames/second:

Alpha value specified for constant blending is not in range [0, 1]. Using alpha 1.0.
Demo Mode: 1920 x 1080 @ 59
running for 5.000000 seconds...

To stop a sample application, press Ctrl+C.

Upstream Sample Application: Gears

The Gears application is an example of an upstream graphics sample application. It is not an NVIDIA application, and is distinct from the NVIDIA sample applications in some ways.

To install and run the Gears application

  1. Boot the target system with an Ethernet connection.

  2. Enable package download from the “universe” repository by editing /etc/apt/sources.list as root:

    $ sudo vi /etc/apt/sources.list
    
  3. Uncomment the following line in the file by removing the leading # character:

    # deb https://ports.ubuntu.com/ubuntu-ports/ bionic universe
    
  4. Update the repository:

    $ sudo apt-get update
    
  5. Install the mesa-utils and mesa-utils-extra packages:

    $ sudo apt-get install -y mesa-utils
    $ sudo apt-get install –y mesa-utils-extra
    
  6. Run the application with these steps:

    $ export DISPLAY=:0
    $ X&
    $ /usr/bin/es2gears
    

    or:

    $ /usr/bin/glxgears