TBM Surface: Providing a Rendering Surface for the Tizen Framework

This tutorial demonstrates how you can create, destroy, map, unmap, and access a surface that is a kind of graphic buffer.

Warm-up

Become familiar with the TBM Surface API basics by learning about:

• Managing the TBM Surface

  Create and manage the TBM surface.

Managing the TBM Surface

To create the TBM surface:

1. To use the functions and data types of the TBM Surface API (in mobile and wearable applications, include the <tbm_surface.h> header file in your application:

   #include <tbm_surface.h>
   

2. Query the formats supported by the system using the tbm_surface_query_formats() function. Free the array of format list after viewing the formats.

   tbm_format *formats;
   uint32_t format_num;
   
   if (tbm_surface_query_formats (&formats, &format_num) != TBM_SURFACE_ERROR_NONE)
   {
      dlog_print (DLOG_ERROR, LOG_TAG, "Failed to get formats supported by the system\n");
   }
   

3. Create the TBM surface (tbm_surface), defining its format, height, and width:

   int i;
   tbm_surface_h surface = NULL;
   
   for (i = 0; i<format_num; i++)
   {
      if (formats[i] == TBM_FORMAT_ARGB8888)
      {
         surface = tbm_surface_create (128, 128, TBM_FORMAT_ARGB8888);
         if (surface == NULL)
            dlog_print (DLOG_ERROR, LOG_TAG, "Failed to create tbm_surface\n");
         break;
      }
   }
   if (i == format_num)
   {
      dlog_print (DLOG_ERROR, LOG_TAG, "format not supported\n");
   }
   

4. Map the TBM surface with the access option. After the surface is mapped, the tbm_surface information is saved in the tbm_surface_info structure:

   tbm_surface_info_s surface_info;
   
   if (tbm_surface_map (surface, TBM_SURF_OPTION_READ|TBM_SURF_OPTION_WRITE, &surface_info) != TBM_SURFACE_ERROR_NONE)
   {
      dlog_print(DLOG_ERROR, LOG_TAG, "Fail to map tbm_surface\n");
   }
   

5. Store data at the tbm_surface by using pointer of each plane:

   for (i = 0; i<surface_info.num_planes; i++)
   {
      memset (surface_info.planes[i].ptr, 0x0, surface_info.planes[i].size);
   }
   

6. Unmap and destroy tbm_surface.

   if (tbm_surface_unmap (surface) != TBM_SURFACE_ERROR_NONE)
   {
      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to unmap tbm_surface\n");
   }
   if (tbm_surface_destroy (surface) != TBM_SURFACE_ERROR_NONE)
   {
      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to destroy tbm_surface\n");
   }
   free (formats);