Embedding 2D and 3D Applications

This chapter covers the things you need to know to create a an OS image that includes 2D and 3D applications and libraries.

Assumptions

This chapter makes the following assumptions:

You understand the process of building an embedded system for QNX Neutrino. For more information, see Building Embedded Systems.
You have your target hardware booting into Neutrino, and can run a shell and commands such as pidin.
You know what graphics hardware you will be using, and its parameters (such as the Vendor and Device IDs for a PCI graphics card).
You'll be using a QNX Neutrino development system to build your embedded target from the command line, or using the System Builder in the IDE.

Building the image

This chapter will walk through building an OS image that runs some of the example applications shipped with QNX Advanced Graphics, illustrating how you'd get your own applications to run on a target system. We'll start with the simplest case, a simple 2D GF application (vsync), and then add various QNX Advanced Graphics components: fonts, image library support, and 3D rendering.

2D example: `vsync`

Let's start with a simple 2D application that requires no extra libraries, the vsync example application. In your buildfile, you require these binaries:

vsync
io-display

Since the 2D library, libgf, is static, it's linked into the application and isn't required on the target. The io-display binary, however, requires some additional DLLs and a configuration file:

a devg-* graphics driver (in this example, devg-coral.so)
the flat frame buffer library, libffb.so.2
the display.conf configuration file, which tells io-display how to start the graphics driver.

In your boot script, you start io-display and pass it the vendor and device IDs for the device you want it to start (the vendor and device combination must have a corresponding entry in display.conf, which specifies, among other things, the graphics driver to use and the display resolution). You should wait for io-display to start before proceeding. For example:

io-display -dvid=0x10cf,did=0x201e
waitfor /dev/io-display/10cf,201e,0

Optionally, you can point io-display to a display.conf using the -c commandline option if you've put it in a location other than /etc/system/config. Otherwise, io-display uses the default /etc/system/config/display.conf.

For more information about configuring io-display, see io-display in the Neutrino Utilities Reference.

If your target has a panel display and uses a Coral-based graphics board, you'll need an additional configuration file. The $QNX_TARGET/processor/usr/photon/config/coral.conf file provides the Coral graphics driver with additional information. See the documentation for devg-coral.so and the coral.conf file itself for more information.

This is what the buildfile now looks like (note that this is exported from the IDE on a Windows host; paths will look a little different on different hosts):

In a real buildfile, you can't use a backslash (\) to break a long line into shorter pieces, but we've done that here, just to make the buildfile easier to read.
The paths to binaries and libraries in your buildfile depend on the version of Momentics installed, and the location it's installed to.

#
#
# GENERATED FILE - QNX System Builder Export
#   Image Type:     ifs
#   Image Sub-type:
#
[virtual=x86,bios] .bootstrap = {
    C:/QNX630/target/qnx6/x86/boot/sys/startup-bios -v
     PATH=/proc/boot:/bin:/usr/bin LD_LIBRARY_PATH=/proc/boot:/lib:/usr/lib \
       C:/QNX630/target/qnx6/x86/boot/sys/procnto -v
}
[+script] .script = {
io-display -dvid=0x10cf,did=0x201e
waitfor /dev/io-display/10cf,201e,0
vsync}
[dperms=0777 uid=0 gid=0]
[gid=0 uid=0 perms=777 data=uip code=uip] /proc/boot/libc.so = libc.so
[type=link] /usr/lib/ldqnx.so.2 = "/proc/boot/libc.so"
[gid=0 uid=0 perms=777 data=copy code=uip] /proc/boot/vsync = \
  "C:/QNX630/workspace2/gui-3d-development_apps-gf/vsync/x86/o/vsync"
[gid=0 uid=0 perms=777 data=uip code=uip] /proc/boot/libffb.so.2 = \
  libffb.so.2
[gid=0 uid=0 perms=777] /usr/photon/config/coral.conf = \
  "C:/QNX630/target/qnx6/x86/usr/photon/config/coral.conf"
[gid=0 uid=0 perms=777] /etc/system/config/display.conf = \
  "C:/QNX630/target/qnx6/etc/system/config/display.conf"
[gid=0 uid=0 perms=777 data=copy code=uip] /proc/boot/io-display = \
  io-display
[gid=0 uid=0 perms=777 data=uip code=uip] /proc/boot/devg-coral.so = \
  devg-coral.so

Font example: `font-cache`

If your application renders fonts, it should use the Font Fusion libraries for Neutrino. Your embedded target only needs one library:

libFF_t2k.so.2

In addition, you'll require:

libm — required by the Font Fusion library
the fonts required by your application — in this example we'll use Prima Sans BT (tt2001m_.ttf)

There are other Font Fusion libraries for the Font Manager functions and font caching, but they are not required by this example. For more information, see the Font Fusion documentation included with QNX Advanced Graphics.

For example, let's add the font-cache example application to the build file you created above. To add these changes to your build file, add these components:

[gid=0 uid=0 perms=777 data=copy code=uip] /proc/boot/font-cache = \
    font-cache
[gid=0 uid=0 perms=777 data=uip code=uip] /proc/boot/libFF-T2K.so.2 = \
    libFF-T2K.so.2
[gid=0 uid=0 perms=777 data=uip code=uip] /proc/boot/libm.so.2 = \
    libm.so.2
[gid=0 uid=0 perms=777] /proc/boot/tt2001m_.ttf = \
    "C:/QNX630/target/qnx6/usr/photon/font_repository/tt2001m_.ttf"

And add this line to your startup script:

font-cache -f tt2001m_.ttf

Image example: `img_decode_simple`

If your application uses the Neutrino image library libimg, you'll need to put any required codecs onto the target (the libary itself is not required since it's static). The codecs are listed in the Working With Images chapter. You also need to include the etc/system/config/img.conf configuration file. You can edit this file and remove the sections for codecs you're not putting on the target (though this is not strictly required since the image library ignores codecs in the file that it can't find). Each section is demarcated by the codec name in square brackets, followed by a mimetype line and list of extensions to associate with the codec. For example, the bitmap codec entry is:

[img_codec_bmp.so]
mime=image/bmp
ext=bmp

Let's add the img_decode_simple binary to your target, and include a couple of sample files to display. You'd add these components to the build file:

[gid=0 uid=0 perms=777 data=copy code=uip] /proc/boot/img_decode_simple = \
    "C:/QNX630/workspace2/img_decode_simple/x86/o/img_decode_simple"
[gid=0 uid=0 perms=777] /etc/system/config/img.conf = \
    "C:/QNX630/target/qnx6/etc/system/config/img.conf"
[gid=0 uid=0 perms=777 data=uip code=uip] /proc/boot/img_codec_jpg.so = \
    img_codec_jpg.so
[gid=0 uid=0 perms=777 data=uip code=uip] /proc/boot/img_codec_png.so = \
    img_codec_png.so
[gid=0 uid=0 perms=777] /proc/boot/example.jpg = \
    "C:/QNX630/workspace2/gf_embed/example.jpg"
[gid=0 uid=0 perms=777] /proc/boot/example.png = \
    "C:/QNX630/workspace2/gf_embed/example.png"

And you'd add this line to the startup script:

img_decode_simple example.jpg

Substitute example.png to open that file instead.

OpenGL ES: Gears

Let's add a 3D application to your buildfile. If your application makes 3D calls, you need to put the appropriate libGLES library on the target, and the application itself. So to add the egl-gears demo application to the buildfile above, add these components:

[gid=0 uid=0 perms=777 data=copy code=uip] /proc/boot/egl-gears = \
    egl-gears
[gid=0 uid=0 perms=777 data=uip code=uip] /proc/boot/libGLES_CM.so.1 = \
    libGLES_CM.so.1

To start this application on the third layer, add this line to the startup script:

egl-gears -layer=3