OpenGLES Texture Streaming - bc-cat User Guide

Introduction

Texture streaming using OpenGL(ES) has a challenge to achieve desirable performance, because the current OpenGL(ES) spec is not designed for dynamic texture changing in an host CPU efficient manner.

bc-cat is a Linux kernel module, which implements Imagination's 3rd Party BufferClass API to provide a shortcut for fast texture streaming on SGX530 graphics accelerator available on the OMAP35x and AM35x platforms. It directly connects the texture buffers to the application to eliminate the overhead of memory copying in OpenGL(ES) texture path. It also utilizes SGX530 to accelerate YUV to RGB color space conversion.

Experiments show that using bc-cat module texture streaming achieves very good performance. Please see the Performance section for details.

Features

• Supports up to 10 texture streaming devices /dev/bccat0~bccat9 (NEW in v0.2.0)
• Supports multiple texture buffers
• Supports many YUV and RGB pixel format textures
• Supports changing texture buffer configuration dynamically during runtime
  • number of buffers
  • buffer size (width and/or height)
  • buffer pixel format
• Supports two texture buffer allocation methods
  • by bc-cat driver
  • by application (such as CMEM buffers)

License

Kernel Module

GPL v2

Unit Test Applications

BSD

Download

The source code is available here, which includes the kernel module and unit test applications.

The release v0.2.0 is available (March 2010). It was tested with PSP v3.0.0.4 & GFX SDK v3.1.0.5. Major changes:

• Added multiple (up to 10, /dev/bccat0~bccat9) texture streaming device support;
• Added automatically create device node '/dev/bccatX' (X is 0~9)
• Runtime checking OMAP/SGX revision to adjust the texture buffer width alignment;
• ioctl BCIOREQ_BUFFERS returns the number of allocated texture buffers; Therefore ioctl BCIOGET_BUFFERCOUNT is isolated;
• Added gles2.0 version test applications; Use 'make OMAP3_ES2x=1' to build them;
• Texture buffer pixel format is defined in bc_cat.h as BC_PIX_FMT_XXXX to remove the dependency on SDK servicesext.h header; This means the applications don't have to be rebuilt when bc-cat kernel module was built with different version of Graphics SDK;

Requirement

The bc-cat v0.2.0 module has been tested on OMAP3 EVM with

• OMAP35x Graphics SDK 3.01.00.05
• OMAP35x PSP SDK 03.00.00.04
• cmem module in DVSDK 3.01.00.04

The bc-cat v0.1.0 module has been tested on OMAP3 EVM with

• OMAP35x Graphics SDK 3.00.00.09
• OMAP35x PSP SDK 02.01.02.09

and AM3517 EVM (rev7) with

• OMAP35x Graphics SDK 3.00.00.09
• AM35x OMAP35x PSP SDK 03.00.00.02, 03.00.00.03

Data Type

bc-cat defines three data types for IOCTLs detailed in next section.

struct BCIO_package_TAG

Used by ioctl BCIOGET_BUFFERCOUNT, BCIOGET_BUFFERPHYADDR, and BCIOGET_BUFFERIDX

typedef struct BCIO_package_TAG {
    int input;    /* input param to driver */
    int output;   /* output param from driver */
} BCIO_package;

struct bc_buf_params

Used by ioctl BCIOREQ_BUFFERS

typedef struct bc_buf_params {
    int count;              /* number of buffers */
    int width;              /* buffer width in pixel, multiple of 8 or 32 */
    int height;             /* buffer height in pixel */
    unsigned int fourcc;    /* buffer pixel format */
    enum BC_memory type;    /* BC_MEMORY_MMAP    - buffers allocated by driver
                             * BC_MEMORY_USERPTR - buffer allocated by app */
} bc_buf_params_t;

Note: member fourcc was defined as 'PVRSRV_PIXEL_FORMAT pixel_fmt' in v0.1.0.

struct bc_buf_ptr

Used by BCIOSET_BUFFERPHYADDR in BC_MEMORY_USERPTR mode

typedef struct bc_buf_ptr {
    unsigned int index;    /* buffer index */
    int size;              /* buffer size */
    unsigned long pa;      /* buffer physical address */
} bc_buf_ptr_t;

IOCTL

bc-cat provides the following IOCTLs to communicate with the application.

BCIOGET_BUFFERCOUNT

Isolated (replaced by BCIOREQ_BUFFERS). Retrieve the number of texture buffers.

BCIOGET_BUFFERPHYADDR

Retrieve the physical address of a given buffer index.

BCIOGET_BUFFERIDX

Retrieve the index of a given buffer physical address.

BCIOREQ_BUFFERS

Request texture buffers. Returns the number of allocated texture buffers.

BCIOSET_BUFFERPHYADDR

Register the external buffer as a texture buffer to a given index. This ioctl should be called before initialize the IMG extensions.

Application Snippet

The following pseudo code shows how application uses bc-cat module to render texture stream.

   Open device '/dev/bc_cat';
   Call ioctl BCIOREQ_BUFFERS to request texture buffers;
   
   if (buffer type == BC_MEMORY_USERPTR) {
       Allocate the external texture buffers;
       Call ioctl BCIOSET_BUFFERPHYADDR to pass the buffer physical address to driver;
   }
   
   Call IMG extensions to query the texture buffer information;
   
   Call ioctl BCIOGET_BUFFERCOUNT to get the number of buffers, which should
   match the buffer info queried through IMG extension in the last step;
   
   if (buffer type == BC_MEMORY_MMAP) {
       Call ioctl BCIOGET_BUFFERPHYADDR to get the physical address of the texture buffers;
       Map them to the virtual space if necessary;
   }
   
   while (rendering loop) {
       Fill the texture data directly into texture buffer;
       Call myglTexBindStreamIMG() to bind the texture;
       Draw the 3D objects;
   }

Build

Please refer to the getting started guide for the graphics SDK available here, it is recommended that you run one of the 3D demo applications from the graphics SDK to make sure you have your configuration and build correct before running using the bc_cat module and unit tests.

To build the bc_cat module and the associated unit tests please follow these instructions:

rules.make
    edit this file and insert the correct paths for your environment.

module
    make
    make install
    make clean

test
    make
    make install
        the test apps will be installed to /opt in target filesystem,
        by default.
    make clean
    make uninstall

By default, 'make' will build frame buffer version of gles1_bc_mmap
and gles1_bc_webcam test apps.

To build gles1_bc_uptr as well, do

    make UPTRBUILD=1

To build X11 version of the gles1_bc_webcam, do

    make X11BUILD=1

To build GLES2.0 version of all the apps, add ''GLES_20=1'' in all the make commands.

    make GLES_20=1, or make GLES_20=1 UPTRBUILD=1, or make GLES_20=1 X11BUILD=1
    make GLES_20=1 install
    make GLES_20=1 clean
    make GLES_20=1 uninstall

The Graphics SDK kernel module has to be patched to support multiple texture devices.

Please apply the patches in below and rebuild the SDK kernel modules by following the Graphics SDK Getting Started Guide.

--- ./GFX_Linux_KM/services4/system/omap3430/sysinfo.h.orig     2009-10-30 01:13:26.000000000 -0500
+++ ./GFX_Linux_KM/services4/system/omap3430/sysinfo.h  2010-02-12 11:20:59.000000000 -0600
@@ -38,7 +38,7 @@

} SYS_DEVICE_TYPE;

-#define SYS_DEVICE_COUNT 3 
+#define SYS_DEVICE_COUNT 15 

#define PRM_REG32(offset)        (offset)
#define CM_REG32(offset)         (offset

--- ./GFX_Linux_KM/services4/srvkm/common/deviceclass.c.orig    2009-10-30 01:13:26.000000000 -0500
+++ ./GFX_Linux_KM/services4/srvkm/common/deviceclass.c 2010-02-12 11:19:55.000000000 -0600
@@ -417,7 +417,12 @@
       psDeviceNode->psSysData = psSysData;

       
-       AllocateDeviceID(psSysData, &psDeviceNode->sDevId.ui32DeviceIndex);
+    if (AllocateDeviceID(psSysData, &psDeviceNode->sDevId.ui32DeviceIndex)
+            != PVRSRV_OK) {
+        PVR_DPF((PVR_DBG_ERROR,"PVRSRVRegisterBCDeviceKM: Failed deviceId alloc"));
+        goto ErrorExit;
+    }
+
       psBCInfo->ui32DeviceID = psDeviceNode->sDevId.ui32DeviceIndex;
       if (pui32DeviceID)
       {

Unit Test

The bc-cat package provides three OpenGL ES1.1 unit test applications, and three OpenGL ES2.0 unit test applications. Please refer to 'INSTALL' and 'README' in the bc-cat package to build and run the test applications.

gles<x>_bc_mmap

It renders a scrolling UYVY color bar pattern onto the six surfaces of a spinning cube using driver allocated texture buffers.

gles<x>_bc_uptr

It is similar to gles<x>_bc_mmap, but using external texture buffers, allocated by CMEM kernel module.

gles<x>_bc_webcam

It renders a USB webcam capture stream onto the six surfaces of the spinning cube. It supports fbdev or X11, selectable in build time.

The USB webcam has to be UVC compliant. Please check http://linux-uvc.berlios.de for the compliant device list.

Note: x = 1, GLES 1.1 version; x = 2, GLES 2.0 version.

Performance

The following number, measured in the unit test applications running on OMAP3 EVM, basically shows the texture streaming performance for rendering a YUV texture in different size on the six surfaces of the cube, using PVR2D_FRONT WSEGL.

   Texture Size       FPS
   ----------------------
      <128x128       >180
       256x256       >170
       512x512       >100
     1024x1024        >50
     1536x1536        >40

Known Issue

• RGB565 pixel format textures are not tested yet.
• Using multiple YUV texture pixel format simultaneously is not supported.