Contents 1 Introduction 2 Feature 3 License 4 Requirement 5 Data Type 6 IOCTL 7 Application Snippet 8 Build 9 Unit Test 10 Performance 11 Known Issue

Introduction

Texture streaming using OpenGL(ES) is a challenge to archive desirable performance, because the current OpenGL(ES) spec is not designed for dynamic texture changing.

bc-cat is a Linux kernel module, which implements Imagination's 3rd Party BufferClass API to provides a shortcut for fast texture streaming on SGX530 graphics accelerator. 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 archives very good performance. Please see Performance section for details.

Feature

• 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

Requirement

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

• OMAP35x Graphics SDK 3.00.00.09
• OMAP35x PSP SDK 02.01.02.09

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 32 */
    int height;                     /* buffer height in pixel */
    PVRSRV_PIXEL_FORMAT pixel_fmt;  /* 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;

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

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.

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 'INSTALL' in the bc-cat package.

Unit Test

The bc-cat package provides three unit test applications, which support both framebuffer and X11 display. Please refer to 'INSTALL' and 'README' in the bc-cat package to build and run the test applications.

gles1_bc_mmap

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

gles1_bc_uptr

It is similar to gles1_bc_mmap, but using external texture buffers, allocated by CMEM kernel module.

gles1_bc_webcam

It renders a USB webcam capture stream onto the six surfaces of the spinning cube.

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

• NV12 and RGB565 pixel format textures are not tested yet.
• Multiple texture buffers in different configurations (such as width, height, or pixel format) simultaneously are not supported yet.
• Only supports texture buffers up to 1.5Kx1.5K in pixel currently.