VGLite API version 2.0 to 3.0 migration guide

The VGLite API version 3.0 is not fully compatible with VGLite API version 2.0. VGLite API version 3.0 includes some new API functions for the new features in the latest VG GPU like GC555. Some VGLite API version 2.0 function interfaces are changed in API version 3.0. So, the existing VGLite API version 2.0 applications must be modified to compile and run properly with the VGLite API version 3.0 driver. This chapter provides guidance for migrating VGLite API version 2.0 applications to VGLite API version 3.0.

VGLite API name changes in API version 3.0

Some original VGLite API names are changed in API version 3.0 for API naming consistency. In the VGLite API version 3.0 header file vg_lite.h, a set of API name macros are defined for the equivalent API names between API version 3.0 and API version 2.0, so it is not necessary to modify the VGLite API function names in API version 2.0 applications for the application to compile and run with the API version 3.0 driver.

The list of equivalent VGLite API functions between API version 3.0 and API version 2.0 is shown below. These API functions’ parameters are the same between API version 3.0 and API version 2.0.

/* API name defines for backward compatibility to VGLite 2.0 APIs */
#define vg_lite_buffer_upload                   vg_lite_upload_buffer
#define vg_lite_path_append                     vg_lite_append_path
#define vg_lite_path_calc_length                vg_lite_get_path_length
#define vg_lite_set_ts_buffer                   vg_lite_set_tess_buffer
#define vg_lite_set_draw_path_type              vg_lite_set_path_type
#define vg_lite_create_mask_layer               vg_lite_create_masklayer
#define vg_lite_fill_mask_layer                 vg_lite_fill_masklayer
#define vg_lite_blend_mask_layer                vg_lite_blend_masklayer
#define vg_lite_generate_mask_layer_by_path     vg_lite_render_masklayer
#define vg_lite_set_mask_layer                  vg_lite_set_masklayer
#define vg_lite_destroy_mask_layer              vg_lite_destroy_masklayer
#define vg_lite_enable_mask                     vg_lite_enable_masklayer
#define vg_lite_enable_color_transformation     vg_lite_enable_color_transform
#define vg_lite_set_color_transformation        vg_lite_set_color_transform
#define vg_lite_set_image_global_alpha          vg_lite_source_global_alpha
#define vg_lite_set_dest_global_alpha           vg_lite_dest_global_alpha
#define vg_lite_clear_rad_grad                  vg_lite_clear_radial_grad
#define vg_lite_update_rad_grad                 vg_lite_update_radial_grad
#define vg_lite_get_rad_grad_matrix             vg_lite_get_radial_grad_matrix
#define vg_lite_set_rad_grad                    vg_lite_set_radial_grad
#define vg_lite_draw_linear_gradient            vg_lite_draw_linear_grad
#define vg_lite_draw_radial_gradient            vg_lite_draw_radial_grad
#define vg_lite_draw_gradient                   vg_lite_draw_grad
#define vg_lite_mem_avail                       vg_lite_get_mem_size
#define vg_lite_set_update_stroke               vg_lite_update_stroke

The list of equivalent VGLite API structures and enumerations is shown below:

#define vg_lite_buffer_image_mode_t             vg_lite_image_mode_t
#define vg_lite_draw_path_type_t                vg_lite_path_type_t
#define vg_lite_linear_gradient_ext_t           vg_lite_ext_linear_gradient_t
#define vg_lite_buffer_transparency_mode_t      vg_lite_transparency_t

Parent topic:VGLite API version 2.0 to 3.0 migration guide

vg_lite_set_scissor API interface change

The VGLite API vg_lite_set_scissor() function name is not changed in API version 3.0, but the API parameters are defined differently in API version 3.0.

In VGLite API version 3.0, the vg_lite_set_scissor() function is defined as:

    /* Set and enable a scissor rectangle for render target. */
    vg_lite_error_t vg_lite_set_scissor(vg_lite_int32_t x, vg_lite_int32_t y,
                  vg_lite_int32_t right, vg_lite_int32_t bottom);

In VGLite API version 2.0, the vg_lite_set_scissor() function is defined as:

    vg_lite_error_t vg_lite_set_scissor(int32_t x, int32_t y, int32_t width, int32_t height);

So, the vg_lite_set_scissor() API parameters “width” and “height” in the VGLite API version 2.0 application must be changed to “right” x-coordinate value and “bottom” y-coordinate value.

Parent topic:VGLite API version 2.0 to 3.0 migration guide

vg_lite_map API interface change

The VGLite API vg_lite_map() function name is not changed in API version 3.0, but the API parameters are defined differently in API version 3.0.

In VGLite API version 3.0, the vg_lite_map() function is defined as:

    /* Map a buffer into hardware accessible address space. */
    vg_lite_error_t vg_lite_map(vg_lite_buffer_t *buffer, vg_lite_map_flag_t flag, int32_t fd);

In VGLite API version 2.0, the vg_lite_map() function is defined as:

    vg_lite_error_t vg_lite_map(vg_lite_buffer_t *buffer);

So, vg_lite_map() in VGLite API version 3.0 API requires two extra parameters “flag” and “fd”, which can simply be set as vg_lite_map (buffer, 0, 0) in applications.

Parent topic:VGLite API version 2.0 to 3.0 migration guide

vg_lite_enable_scissor / vg_lite_disable_scissor API

The VGLite API vg_lite_enable_scissor() and vg_lite_disable_scissor() functions are valid only for vg_lite_scissor_rects() API. They have no effect for vg_lite_set_scissor() in VGLite API version 3.0.

Although the behavior of vg_lite_enable_scissor() and vg_lite_disable_scissor() is changed in VGLite API version 3.0, there is no need to change these functions in VGLite API version 2.0 applications to work with the VGLite API version 3.0 driver.

Parent topic:VGLite API version 2.0 to 3.0 migration guide

vg_lite_draw_pattern API interface change

The VGLite API vg_lite_draw_pattern() function name is not changed in API version 3.0, but the API parameters are defined differently in API version 3.0.

In VGLite API version 3.0, the vg_lite_draw_pattern() function is defined as:

    /* Draw a path that is filled by a transformed image pattern. */
    vg_lite_error_t vg_lite_draw_pattern(vg_lite_buffer_t *target,
                                    vg_lite_path_t *path,
                                    vg_lite_fill_t fill_rule,
                                    vg_lite_matrix_t *path_matrix,
                                    vg_lite_buffer_t *pattern_image,
                                    vg_lite_matrix_t *pattern_matrix,
                                    vg_lite_blend_t blend,
                                    vg_lite_pattern_mode_t pattern_mode,
                                    vg_lite_color_t  pattern_color,
                                    vg_lite_color_t  color,
                                    vg_lite_filter_t filter);

Compared to the VGLite API version 2.0 vg_lite_draw_pattern() function, “color” is a new additional parameter. It specifies a 32bpp ARGB color (vg_lite_color_t) to be applied as a mix color. If nonzero, the mix color value gets multiplied with each source pixel before blending happens. If a mix color is not needed, set the color parameter to 0.

Parent topic:VGLite API version 2.0 to 3.0 migration guide

[New] vg_lite_copy_image in VGLite API version 3.0

The new API vg_lite_copy_image() is added in VGLite API version 3.0 to support the OpenVG vgCopyImage API, which performs a pixel rectangle copy without pixel transformation, blending, filtering operations.

Parent topic:VGLite API version 2.0 to 3.0 migration guide

vg_lite_set_dither API is deprecated in API version 3.0

The original API version 2.0 function vg_lite_set_dither(int enable) API is removed from API version 3.0, it is replaced with two new APIs for dither enable/disable:


    /* Enable dither function. Dither is OFF by default. */
    vg_lite_error_t vg_lite_enable_dither();
    /* Disable dither function. Dither is OFF by default. */
    vg_lite_error_t vg_lite_disable_dither();

Therefore, the vg_lite_set_dither(enable) function in the VGLite API version 2.0 application must be replaced with vg_lite_enable_dither() or vg_lite_disable_dither() to work with the VGLite API version 3.0 driver.

Parent topic:VGLite API version 2.0 to 3.0 migration guide

Deprecated VGLite API version 2.0 functions

The VGLite API vg_lite_perspective(), vg_lite_enable_premultiply(), vg_lite_disable_premultiply() functions are removed from API version 3.0. These API functions must be deleted from a VGLite API version 2.0 application to work with the VGLite API version 3.0 driver.

In VGLite API version 3.0, the color premultiply setting is defined by the vg_lite_blend_t enumeration to replace the original vg_lite_enable_premultiply() and vg_lite_disable_premultiply() APIs.

  • VG_LITE_BLEND_* enumeration values in vg_lite_blend_t define non-premultiplied blending modes.

  • OPEVG_BLEND_* enumeration values in vg_lite_blend_t define premultiplied Porter-Duff blending modes.

So, the VGLite API version 3.0 application can set different blending modes to get the desired premultiplied/non-premultiplied blending result.

Parent topic:VGLite API version 2.0 to 3.0 migration guide