net.rim.device.api.openvg
Interface VG11

All Superinterfaces:
VG, VG10

public interface VG11
extends VG10

The VG11 interface contains the BlackBerry Java(TM) programming language bindings for OpenVG(R) 1.1 extending the OpenVG 1.0 core functionality.

OpenVG documentation is available at the Khronos web site.

OpenVG provides a drawing model similar to those of existing two-dimensional drawing APIs and formats, such as Adobe PostScript [ADOB99], PDF [ADOB06a], Adobe (formerly MacroMedia) Flash [ADOB06b]; Sun Microsystems Java2D [SUN04]; and W3C SVG [SVGF05][SVGT06]. Version 1.1 is specifically intended to support all drawing features required by a SVG Tiny 1.2 renderer or an Adobe Flash Lite renderer (implementing the Flash 7 feature set), and additionally to support functions that may be of use for implementing an SVG Basic renderer.

OpenVG is intended to provide a hardware abstraction layer that will allow accelerated performance on a variety of application platforms. Functions that are not expected to be amenable to hardware acceleration in the near future were either not included, or included as part of the optional VGU utility library. Where possible, the syntax of OpenVG is intended to be reminiscent of that of OpenGL, in order to make learning OpenVG as easy as possible for OpenGL developers. Most of the OpenVG state is encapsulated in a set of primitive-valued variables that are manipulated using the vgSet and vgGet functions. Extensions may add new state variables in order to add new features to the pipeline without needing to add new functions.

Paint, path, and image objects in OpenVG are referenced using opaque handles. This allows implementations to store such objects using their own preferred representation, in whatever form of memory they choose. This is intended to simplify hardware design, and to minimize processing and bus traffic for frequently-used objects.

Font Sharing

Mobile platforms usually provide a limited number of resident fonts. These fonts are available for use by any application that is running on a device, and the same font could be used by more than one application utilizing OpenVG. The sharing of VGFont objects may increase the efficiency of using OpenVG memory and other resources.

In order for VGFont objects to be shared, the VGFont (and underlying VGPath and VGImage objects) must be bound to a shared context. In addition, applications that create a font must share the following additional information about the font object: - the relationship between original fonts and VGFont object created by the application; - the character subset for which a particular VGFont object was created (if applicable); - the point or 'pixels per EM' size (if applicable), for which VGFont object was created; - the custom mapping between character codes and glyph indices in the VGFont object.

In order to avoid additional complexity associated with character-to-glyph mapping, it is recommended that shared VGFont objects utilize character-toglyph mappings based on either Unicode or native OpenType/TrueType glyph indices., as the use of custom glyph indices requires maintaining a standalone character-to glyph mapping table for each VGFont object.

Text Layout and Rendering

OpenVG provides a dedicated glyph rendering API to assist applications in compositing, layout, and rendering of text. Implementations may apply specific optimizations for rendering of glyphs. For example, auto-hinting algorithms that attempt to “snap” glyph outlines to the pixel grid may be used to improve the quality of text rendering for VGFont objects that contain unhinted glyph outlines. Autohinting may not be appropriate for animated text or when precise glyph placement is required.

See Also:
VGUtils, EGL12
Since:
BlackBerry API 6.0.0

Field Summary
static int OPENVG_VERSION_1_1
          OpenVG 1. constant.
static int VG_A_1
          OpenVG 1. constant.
static int VG_A_4
          OpenVG 1. constant.
static int VG_COLOR_TRANSFORM
          OpenVG 1. constant.
static int VG_COLOR_TRANSFORM_VALUES
          OpenVG 1. constant.
static int VG_FONT_NUM_GLYPHS
          OpenVG 1. constant.
static int VG_GLYPH_ORIGIN
          OpenVG 1. constant.
static int VG_MATRIX_GLYPH_USER_TO_SURFACE
          OpenVG 1. constant.
 
Fields inherited from interface net.rim.device.api.openvg.VG10
VG_ABSOLUTE, VG_ALPHA, VG_A_8, VG_BAD_HANDLE_ERROR, VG_BLEND_ADDITIVE, VG_BLEND_DARKEN, VG_BLEND_DST_IN, VG_BLEND_DST_OVER, VG_BLEND_LIGHTEN, VG_BLEND_MODE, VG_BLEND_MULTIPLY, VG_BLEND_SCREEN, VG_BLEND_SRC, VG_BLEND_SRC_IN, VG_BLEND_SRC_OVER, VG_BLUE, VG_BW_1, VG_CAP_BUTT, VG_CAP_ROUND, VG_CAP_SQUARE, VG_CLEAR_COLOR, VG_CLEAR_MASK, VG_CLOSE_PATH, VG_COLOR_RAMP_SPREAD_PAD, VG_COLOR_RAMP_SPREAD_REFLECT, VG_COLOR_RAMP_SPREAD_REPEAT, VG_CUBIC_TO, VG_CUBIC_TO_ABS, VG_CUBIC_TO_REL, VG_DRAW_IMAGE_MULTIPLY, VG_DRAW_IMAGE_NORMAL, VG_DRAW_IMAGE_STENCIL, VG_EVEN_ODD, VG_EXTENSIONS, VG_FALSE, VG_FILL_MASK, VG_FILL_PATH, VG_FILL_RULE, VG_FILTER_CHANNEL_MASK, VG_FILTER_FORMAT_LINEAR, VG_FILTER_FORMAT_PREMULTIPLIED, VG_GREEN, VG_HARDWARE_ACCELERATED, VG_HARDWARE_UNACCELERATED, VG_HLINE_TO, VG_HLINE_TO_ABS, VG_HLINE_TO_REL, VG_ILLEGAL_ARGUMENT_ERROR, VG_IMAGE_FORMAT, VG_IMAGE_FORMAT_QUERY, VG_IMAGE_HEIGHT, VG_IMAGE_IN_USE_ERROR, VG_IMAGE_MODE, VG_IMAGE_QUALITY, VG_IMAGE_QUALITY_BETTER, VG_IMAGE_QUALITY_FASTER, VG_IMAGE_QUALITY_NONANTIALIASED, VG_IMAGE_WIDTH, VG_INTERSECT_MASK, VG_INVALID_HANDLE, VG_JOIN_BEVEL, VG_JOIN_MITER, VG_JOIN_ROUND, VG_LCCWARC_TO, VG_LCCWARC_TO_ABS, VG_LCCWARC_TO_REL, VG_LCWARC_TO, VG_LCWARC_TO_ABS, VG_LCWARC_TO_REL, VG_LINE_TO, VG_LINE_TO_ABS, VG_LINE_TO_REL, VG_MASKING, VG_MATRIX_FILL_PAINT_TO_USER, VG_MATRIX_IMAGE_USER_TO_SURFACE, VG_MATRIX_MODE, VG_MATRIX_PATH_USER_TO_SURFACE, VG_MATRIX_STROKE_PAINT_TO_USER, VG_MAX_COLOR_RAMP_STOPS, VG_MAX_DASH_COUNT, VG_MAX_FLOAT, VG_MAX_GAUSSIAN_STD_DEVIATION, VG_MAX_IMAGE_BYTES, VG_MAX_IMAGE_HEIGHT, VG_MAX_IMAGE_PIXELS, VG_MAX_IMAGE_WIDTH, VG_MAX_KERNEL_SIZE, VG_MAX_SCISSOR_RECTS, VG_MAX_SEPARABLE_KERNEL_SIZE, VG_MOVE_TO, VG_MOVE_TO_ABS, VG_MOVE_TO_REL, VG_NON_ZERO, VG_NO_CONTEXT_ERROR, VG_NO_ERROR, VG_OUT_OF_MEMORY_ERROR, VG_PAINT_COLOR, VG_PAINT_COLOR_RAMP_PREMULTIPLIED, VG_PAINT_COLOR_RAMP_SPREAD_MODE, VG_PAINT_COLOR_RAMP_STOPS, VG_PAINT_LINEAR_GRADIENT, VG_PAINT_PATTERN_TILING_MODE, VG_PAINT_RADIAL_GRADIENT, VG_PAINT_TYPE, VG_PAINT_TYPE_COLOR, VG_PAINT_TYPE_LINEAR_GRADIENT, VG_PAINT_TYPE_PATTERN, VG_PAINT_TYPE_RADIAL_GRADIENT, VG_PATH_BIAS, VG_PATH_CAPABILITY_ALL, VG_PATH_CAPABILITY_APPEND_FROM, VG_PATH_CAPABILITY_APPEND_TO, VG_PATH_CAPABILITY_ERROR, VG_PATH_CAPABILITY_INTERPOLATE_FROM, VG_PATH_CAPABILITY_INTERPOLATE_TO, VG_PATH_CAPABILITY_MODIFY, VG_PATH_CAPABILITY_PATH_BOUNDS, VG_PATH_CAPABILITY_PATH_LENGTH, VG_PATH_CAPABILITY_PATH_TRANSFORMED_BOUNDS, VG_PATH_CAPABILITY_POINT_ALONG_PATH, VG_PATH_CAPABILITY_TANGENT_ALONG_PATH, VG_PATH_CAPABILITY_TRANSFORM_FROM, VG_PATH_CAPABILITY_TRANSFORM_TO, VG_PATH_DATATYPE, VG_PATH_DATATYPE_F, VG_PATH_DATATYPE_QUERY, VG_PATH_DATATYPE_S_16, VG_PATH_DATATYPE_S_32, VG_PATH_DATATYPE_S_8, VG_PATH_FORMAT, VG_PATH_FORMAT_STANDARD, VG_PATH_NUM_COORDS, VG_PATH_NUM_SEGMENTS, VG_PATH_SCALE, VG_PIXEL_LAYOUT, VG_PIXEL_LAYOUT_BGR_HORIZONTAL, VG_PIXEL_LAYOUT_BGR_VERTICAL, VG_PIXEL_LAYOUT_RGB_HORIZONTAL, VG_PIXEL_LAYOUT_RGB_VERTICAL, VG_PIXEL_LAYOUT_UNKNOWN, VG_QUAD_TO, VG_QUAD_TO_ABS, VG_QUAD_TO_REL, VG_RED, VG_RELATIVE, VG_RENDERER, VG_RENDERING_QUALITY, VG_RENDERING_QUALITY_BETTER, VG_RENDERING_QUALITY_FASTER, VG_RENDERING_QUALITY_NONANTIALIASED, VG_SCCWARC_TO, VG_SCCWARC_TO_ABS, VG_SCCWARC_TO_REL, VG_SCISSORING, VG_SCISSOR_RECTS, VG_SCREEN_LAYOUT, VG_SCUBIC_TO, VG_SCUBIC_TO_ABS, VG_SCUBIC_TO_REL, VG_SCWARC_TO, VG_SCWARC_TO_ABS, VG_SCWARC_TO_REL, VG_SET_MASK, VG_SQUAD_TO, VG_SQUAD_TO_ABS, VG_SQUAD_TO_REL, VG_STROKE_CAP_STYLE, VG_STROKE_DASH_PATTERN, VG_STROKE_DASH_PHASE, VG_STROKE_DASH_PHASE_RESET, VG_STROKE_JOIN_STYLE, VG_STROKE_LINE_WIDTH, VG_STROKE_MITER_LIMIT, VG_STROKE_PATH, VG_SUBTRACT_MASK, VG_TILE_FILL, VG_TILE_FILL_COLOR, VG_TILE_PAD, VG_TILE_REFLECT, VG_TILE_REPEAT, VG_TRUE, VG_UNION_MASK, VG_UNSUPPORTED_IMAGE_FORMAT_ERROR, VG_UNSUPPORTED_PATH_FORMAT_ERROR, VG_VENDOR, VG_VERSION, VG_VLINE_TO, VG_VLINE_TO_ABS, VG_VLINE_TO_REL, VG_lABGR_8888, VG_lABGR_8888_PRE, VG_lARGB_8888, VG_lARGB_8888_PRE, VG_lBGRA_8888, VG_lBGRA_8888_PRE, VG_lBGRX_8888, VG_lL_8, VG_lRGBA_8888, VG_lRGBA_8888_PRE, VG_lRGBX_8888, VG_lXBGR_8888, VG_lXRGB_8888, VG_sABGR_1555, VG_sABGR_4444, VG_sABGR_8888, VG_sABGR_8888_PRE, VG_sARGB_1555, VG_sARGB_4444, VG_sARGB_8888, VG_sARGB_8888_PRE, VG_sBGRA_4444, VG_sBGRA_5551, VG_sBGRA_8888, VG_sBGRA_8888_PRE, VG_sBGRX_8888, VG_sBGR_565, VG_sL_8, VG_sRGBA_4444, VG_sRGBA_5551, VG_sRGBA_8888, VG_sRGBA_8888_PRE, VG_sRGBX_8888, VG_sRGB_565, VG_sXBGR_8888, VG_sXRGB_8888
 
Method Summary
 void vgClearGlyph(int font, int glyphIndex)
          The vgClearGlyph deletes the glyph defined by a glyphIndex parameter from a font.
 void vgCopyMask(int maskLayer, int dx, int dy, int sx, int sy, int width, int height)
          The vgCopyMask copies a portion of the current surface mask into a VGMaskLayer object.
 int vgCreateFont(int glyphCapacityHint)
          The vgCreateFont creates a new font object and returns a VGFont handle to it.
 int vgCreateMaskLayer(int width, int height)
          The vgCreateMaskLayer creates an object capable of storing a mask layer with the give width and height and returns a VGMaskLayer handle to it.
 void vgDestroyFont(int font)
          The vgDestroyFont destroys the VGFont object pointed to by the font argument.Note that vgDestroyFont will not destroy underlying objects that were used to define glyphs in the font.
 void vgDestroyMaskLayer(int maskLayer)
          The vgDestroyPath releases any resources associated with a mask layer may be deallocated by calling vgDestroyMaskLayer.
 void vgDrawGlyph(int font, int glyphIndex, int paintModes, boolean allowAutoHinting)
          The vgDrawGlyph renders a glyph defined by the glyphIndex using the given font object.
 void vgDrawGlyphs(int font, int glyphCount, int[] glyphIndices, int glyphIndicesOffset, float[] adjustments_x, int adjustments_xOffset, float[] adjustments_y, int adjustments_yOffset, int paintModes, boolean allowAutoHinting)
          The vgDrawGlyphs renders a sequence of glyphs defined by the array pointed to by glyphIndices using the given font object.
 void vgFillMaskLayer(int maskLayer, int x, int y, int width, int height, float value)
          The vgFillMaskLayer function sets the values of a given maskLayer within a given rectangular region to a given value.
 void vgRenderToMask(int path, int paintModes, int operation)
          The vgRenderToMask function modifies the current surface mask by applying the given operation to the set of coverage values associated with the rendering of the given path.
 void vgSetGlyphToImage(int font, int glyphIndex, int image, float[] glyphOrigin, int glyphOriginOffset, float[] escapement, int escapementOffset)
          The vgSetGlyphToImage creates a new glyph and assigns the given image into a glyph associated with the glyphIndex in a font object.
 void vgSetGlyphToPath(int font, int glyphIndex, int path, boolean isHinted, float[] glyphOrigin, int glyphOriginOffset, float[] escapement, int escapementOffset)
          The vgSetGlyphToPath creates a new glyph and assigns the given path to a glyph associated with the glyphIndex in a font object.
 
Methods inherited from interface net.rim.device.api.openvg.VG10
vgAppendPath, vgAppendPathData, vgChildImage, vgClear, vgClearImage, vgClearPath, vgColorMatrix, vgColorMatrix, vgConvolve, vgCopyImage, vgCopyPixels, vgCreateImage, vgCreatePaint, vgCreatePath, vgDestroyImage, vgDestroyPaint, vgDestroyPath, vgDrawImage, vgDrawPath, vgFinish, vgFlush, vgGaussianBlur, vgGetColor, vgGetError, vgGetImageSubData, vgGetMatrix, vgGetMatrix, vgGetPaint, vgGetParameterVectorSize, vgGetParameterf, vgGetParameterfv, vgGetParameterfv, vgGetParameteri, vgGetParameteriv, vgGetParameteriv, vgGetParent, vgGetPathCapabilities, vgGetPixels, vgGetString, vgGetVectorSize, vgGetf, vgGetfv, vgGetfv, vgGeti, vgGetiv, vgGetiv, vgHardwareQuery, vgImageSubData, vgInterpolatePath, vgLoadIdentity, vgLoadMatrix, vgLoadMatrix, vgLookup, vgLookupSingle, vgMask, vgModifyPathCoords, vgMultMatrix, vgMultMatrix, vgPaintPattern, vgPathBounds, vgPathBounds, vgPathLength, vgPathTransformedBounds, vgPathTransformedBounds, vgPointAlongPath, vgPointAlongPath, vgReadPixels, vgRemovePathCapabilities, vgRotate, vgScale, vgSeparableConvolve, vgSetColor, vgSetPaint, vgSetParameterf, vgSetParameterfv, vgSetParameterfv, vgSetParameteri, vgSetParameteriv, vgSetParameteriv, vgSetPixels, vgSetf, vgSetfv, vgSetfv, vgSeti, vgSetiv, vgSetiv, vgShear, vgTransformPath, vgTranslate, vgWritePixels
 



Field Detail

OPENVG_VERSION_1_1

static final int OPENVG_VERSION_1_1
OpenVG 1. constant.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VG_COLOR_TRANSFORM

static final int VG_COLOR_TRANSFORM
OpenVG 1. constant.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VG_COLOR_TRANSFORM_VALUES

static final int VG_COLOR_TRANSFORM_VALUES
OpenVG 1. constant.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VG_GLYPH_ORIGIN

static final int VG_GLYPH_ORIGIN
OpenVG 1. constant.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VG_MATRIX_GLYPH_USER_TO_SURFACE

static final int VG_MATRIX_GLYPH_USER_TO_SURFACE
OpenVG 1. constant.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VG_A_1

static final int VG_A_1
OpenVG 1. constant.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VG_A_4

static final int VG_A_4
OpenVG 1. constant.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VG_FONT_NUM_GLYPHS

static final int VG_FONT_NUM_GLYPHS
OpenVG 1. constant.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Method Detail

vgRenderToMask

void vgRenderToMask(int path,
                    int paintModes,
                    int operation)
The vgRenderToMask function modifies the current surface mask by applying the given operation to the set of coverage values associated with the rendering of the given path.

If paintModes contains VG_FILL_PATH, the path is filled; if it contains VG_STROKE_PATH, the path is stroked. If both are present, the mask operation is performed in two passes, first on the filled path geometry, then on the stroked path geometry.

Conceptually, for each pass, an intermediate single-channel image is initialized to 0, then filled with those coverage values that would result from the first four stages of the OpenVG pipeline (i.e., state setup, stroked path generation if applicable, transformation, and rasterization) when drawing a path with vgDrawPath using the given set of paint modes and all current OpenVG state settings that affect path rendering (scissor rectangles, rendering quality, fill rule, stroke parameters, etc.). Paint settings (e.g., paint matrices) are ignored. Finally, the drawing surface mask is modified as though vgMask were called using the intermediate image as the mask parameter. Changes to path following this call do not affect the mask. If operation is VG_CLEAR_MASK or VG_FILL_MASK, path is ignored and the entire mask is affected.

An implementation that supports geometric clipping of primitives may cache the contents of path and make use of it directly when primitives are drawn, without generating a rasterized version of the clip mask. Other implementation-specific optimizations may be used to avoid materializing a full intermediate mask image.

Errors:

VG_BAD_HANDLE_ERROR is generated:

VG_ILLEGAL_ARGUMENT_ERROR is generated: VG_ILLEGAL_ARGUMENT_ERROR is generated:

Parameters:
path - The associate path to render the mask on.
paintModes - The paintModes to be used.
operation - Operation used to modify the alpha masks.
See Also:
VG10.vgMask(int, int, int, int, int, int)
Since:
BlackBerry API 6.0.0

vgCreateMaskLayer

int vgCreateMaskLayer(int width,
                      int height)
The vgCreateMaskLayer creates an object capable of storing a mask layer with the give width and height and returns a VGMaskLayer handle to it. The mask layer is defined to be compatible with the format and multisampling properties of the current drawing surface. If there is no current drawing surface, no mask is configured for the current drawing surface, or an error occurs, VG_INVALID_HANDLE is returned. All mask layer values are initially set to one.

Errors:

VG_ILLEGAL_ARGUMENT_ERROR is generated:

Parameters:
width - The mask layer width.
height - The mask layer height.
Returns:
VGMaskLayer handle to the newly created mask layer; VG_INVALID_HANDLE if an error occurs.
Since:
BlackBerry API 6.0.0

vgDestroyMaskLayer

void vgDestroyMaskLayer(int maskLayer)
The vgDestroyPath releases any resources associated with a mask layer may be deallocated by calling vgDestroyMaskLayer. Following the call, the maskLayer handle is no longer valid in the current context.

Errors:

VG_BAD_HANDLE_ERROR is generated:

Parameters:
maskLayer - The mask layer to be destroyed.
Since:
BlackBerry API 6.0.0

vgFillMaskLayer

void vgFillMaskLayer(int maskLayer,
                     int x,
                     int y,
                     int width,
                     int height,
                     float value)
The vgFillMaskLayer function sets the values of a given maskLayer within a given rectangular region to a given value. The floating-point value value must be between 0 and 1. The value is rounded to the closest available value supported by the mask layer. If two values are equally close, the larger value is used.

Errors:

VG_BAD_HANDLE_ERROR is generated:

  • if maskLayer is not a valid mask handle.
VG_ILLEGAL_ARGUMENT_ERROR is generated:

Parameters:
maskLayer - The mask layer to be filled.
x - The rectangle x position to fill within.
y - The rectangle y position to fill within.
width - The rectangle width position to fill within.
height - The rectangle height position to fill within.
value - The float value to be filled into the specified rectangular region between 0 - 1.
Since:
BlackBerry API 6.0.0

vgCopyMask

void vgCopyMask(int maskLayer,
                int dx,
                int dy,
                int sx,
                int sy,
                int width,
                int height)
The vgCopyMask copies a portion of the current surface mask into a VGMaskLayer object. The source region starts at (sx, sy) in the surface mask, and the destination region starts at (dx, dy) in the destination maskLayer. The copied region is clipped to the given width and height and the bounds of the source and destination. If the current context does not contain a surface mask, vgCopyMask does nothing.

Errors:

VG_BAD_HANDLE_ERROR is generated:

VG_ILLEGAL_ARGUMENT_ERROR is generated:

Parameters:
maskLayer - The mask layer to be copied.
dx - The destination x region.
dy - The destination y region.
sx - The source starting x region.
sy - The source starting y region.
width - The width bounds to be copied.
height - The height bounds to be copied.
Since:
BlackBerry API 6.0.0

vgCreateFont

int vgCreateFont(int glyphCapacityHint)
The vgCreateFont creates a new font object and returns a VGFont handle to it. The glyphCapacityHint argument provides a hint as to the capacity of a VGFont, i.e., the total number of glyphs that this VGFont object will be required to accept. A value of 0 indicates that the value is unknown. If an error occurs during execution, VG_INVALID_HANDLE is returned.

Errors:

VG_ILLEGAL_ARGUMENT_ERROR is generated:

Parameters:
glyphCapacityHint - The font glyph capacity or 0 if unknown.
Returns:
VGFont handle to the newly created font; VG_INVALID_HANDLE if an error occurs.
Since:
BlackBerry API 6.0.0

vgDestroyFont

void vgDestroyFont(int font)
The vgDestroyFont destroys the VGFont object pointed to by the font argument.Note that vgDestroyFont will not destroy underlying objects that were used to define glyphs in the font. It is the responsibility of an application to destroy all VGPath or VGImage objects that were used in a VGFont, if they are no longer in use.

Errors:

VG_BAD_HANDLE_ERROR is generated:

Parameters:
font - The font to be destroyed.
Since:
BlackBerry API 6.0.0

vgSetGlyphToPath

void vgSetGlyphToPath(int font,
                      int glyphIndex,
                      int path,
                      boolean isHinted,
                      float[] glyphOrigin,
                      int glyphOriginOffset,
                      float[] escapement,
                      int escapementOffset)
The vgSetGlyphToPath creates a new glyph and assigns the given path to a glyph associated with the glyphIndex in a font object. The glyphOrigin argument defines the coordinates of the glyph origin within the path, and the escapement parameter determines the advance width for this glyph. Both glyphOrigin and escapement coordinates are defined in the same coordinate system as the path. For glyphs that have no visual representation (e.g., the character), a value of VG_INVALID_HANDLE is used for path. The reference count for the path is incremented.

The path object may define either an original glyph outline, or an outline that has been scaled and hinted to a particular size (in surface coordinate units); this is defined by the isHinted parameter, which can be used by implementation for text-specific optimizations (e.g., heuristic auto-hinting of unhinted outlines). When isHinted is equal to VG_TRUE, the implementation will never apply auto-hinting; otherwise, auto hinting will be applied at the implementation's discretion.

Errors:

VG_BAD_HANDLE_ERROR is generated:

  • if font is not a valid font handle, or is not shared with the current context.
  • if path is not a valid path handle or VG_INVALID_HANDLE, or is not shared with the current context.
VG_ILLEGAL_ARGUMENT_ERROR is generated:
  • if glyphOrigin or escapement is null or is not properly aligned.

Parameters:
font - The font to set the glyph path to.
glyphIndex - The glyph to set the path for.
path - The path to be used for the specified glyph index.
isHinted - true if auto-hinting is applied; false if not.
glyphOrigin - The orgin for the glyph.
glyphOriginOffset - The offset into the glyphOrigin array.
escapement - The advance width for this glyph.
escapementOffset - The offset into the escapement array.
Throws:
IllegalArgumentException - if glyphOriginOffset is negative or glyphOrigin.length - glyphOriginOffset is less than 2.
IllegalArgumentException - if escapementOffset is negative or escapement.length - escapementOffset is less than 2.
Since:
BlackBerry API 6.0.0

vgSetGlyphToImage

void vgSetGlyphToImage(int font,
                       int glyphIndex,
                       int image,
                       float[] glyphOrigin,
                       int glyphOriginOffset,
                       float[] escapement,
                       int escapementOffset)
The vgSetGlyphToImage creates a new glyph and assigns the given image into a glyph associated with the glyphIndex in a font object. The glyphOrigin argument defines the coordinates of the glyph origin within the image, and the escapement parameter determines the advance width for this glyph. Both glyphOrigin and escapement coordinates are defined in the image coordinate system. Applying transformations to an image (other than translations mapped to pixel grid in surface coordinate system) should be avoided as much as possible. For glyphs that have no visual representation (e.g., the character), a value of VG_INVALID__HANDLE is used for image. The reference count for the image is incremented.

Errors:

VG_BAD_HANDLE_ERROR is generated:

  • if font is not a valid font handle, or is not shared with the current context.
  • if image is not a valid image handle or VG_INVALID_HANDLE, or is not shared with the current context.
VG_ILLEGAL_ARGUMENT_ERROR is generated:
  • if glyphOrigin or escapement is null or is not properly aligned.
VG_IMAGE_IN_USE_ERROR is generated:
  • if image is currently a rendering target.

Parameters:
font - The font to set the glyph path to.
glyphIndex - The glyph to set the path for.
image - The image to be used as the glyph
glyphOrigin - The orgin for the glyph.
glyphOriginOffset - The offset into the glyphOrigin array.
escapement - The advance width for this glyph.
escapementOffset - The offset into the escapement array.
Throws:
IllegalArgumentException - if glyphOriginOffset is negative or glyphOrigin.length - glyphOriginOffset is less than 2.
IllegalArgumentException - if escapementOffset is negative or escapement.length - escapementOffset is less than 2.
Since:
BlackBerry API 6.0.0

vgClearGlyph

void vgClearGlyph(int font,
                  int glyphIndex)
The vgClearGlyph deletes the glyph defined by a glyphIndex parameter from a font. The reference count for the VGPath or VGImage object to which the glyph was previously set is decremented, and the object's resources are released if the count has fallen to 0.

Errors:

VG_BAD_HANDLE_ERROR is generated:

  • if font is not a valid font handle, or is not shared with the current context.
VG_ILLEGAL_ARGUMENT_ERROR is generated:
  • if glyphIndex is not defined for the font.

Parameters:
font - The font to clear the glyph index on.
glyphIndex - The glyph index to be cleared.
Since:
BlackBerry API 6.0.0

vgDrawGlyph

void vgDrawGlyph(int font,
                 int glyphIndex,
                 int paintModes,
                 boolean allowAutoHinting)
The vgDrawGlyph renders a glyph defined by the glyphIndex using the given font object. The user space position of the glyph (the point where the glyph origin will be placed) is determined by value of VG_GLYPH_ORIGIN. vgDrawGlyph calculates the new text origin by translating the glyph origin by the escapement vector of the glyph defined by glyphIndex. Following the call, the VG_GLYPH_ORIGIN parameter will be updated with the new origin. The paintModes parameter controls how glyphs are rendered. If paintModes is 0, neither VGImage-based nor VGPath-based glyphs are drawn. This mode is useful for determining the metrics of the glyph sequence. If paintModes is equal to one of VG_FILL_PATH, VG_STROKE_PATH, or (VG_FILL_PATH | VG_STROKE_PATH), path-based glyphs are filled, stroked (outlined), or both, respectively, and image-based glyphs are drawn. When the allowAutoHinting flag is set to VG_FALSE, rendering occurs without hinting. If allowAutoHinting is equal to VG_TRUE, autohinting may be optionally applied to alter the glyph outlines slightly for better rendering quality. In this case, the escapement values will be adjusted to match the effects of hinting. Autohinting is not applied to image-based glyphs or path-based glyphs marked as isHinted in vgSetGlyphToPath.

Errors:

VG_BAD_HANDLE_ERROR is generated:

  • if font is not a valid font handle, or is not shared with the current context.
VG_ILLEGAL_ARGUMENT_ERROR is generated:
  • if glyphIndex has not been defined for a given font object.
  • if paintModes is not a valid bitwise OR of values from VG_FILL_PATH or VG_STROKE_PATH.

Parameters:
font - The font to draw the glyph from.
glyphIndex - The index of the glyph to be drawn.
paintModes - The paintModes to be used.
allowAutoHinting - true if auto-hinting is allowed; false if not.
Since:
BlackBerry API 6.0.0

vgDrawGlyphs

void vgDrawGlyphs(int font,
                  int glyphCount,
                  int[] glyphIndices,
                  int glyphIndicesOffset,
                  float[] adjustments_x,
                  int adjustments_xOffset,
                  float[] adjustments_y,
                  int adjustments_yOffset,
                  int paintModes,
                  boolean allowAutoHinting)
The vgDrawGlyphs renders a sequence of glyphs defined by the array pointed to by glyphIndices using the given font object. The values in the adjustments_x and adjustments_y arrays define positional adjustment values for each pair of glyphs defined by the glyphIndices array. The glyphCount parameter defines the number of elements in the glyphIndices and adjustments_x and adjustments_y arrays. The adjustment values defined in these arrays may represent kerning or other positional adjustments required for each pair of glyphs. If no adjustments for glyph positioning in a particular axis are required (all horizontal and/or vertical adjustments are zero), null's may be passed for either or both of adjustment_x and adjustment_y. The adjustments values should be defined in the same coordinate system as the font glyphs; if the glyphs are defined by path objects with path data scaled (e.g., by a factor of 1/units-per-EM), the values in the adjustment_x and adjustment_y arrays are scaled using the same scale factor.

Errors:

VG_BAD_HANDLE_ERROR is generated:

  • if font is not a valid font handle, or is not shared with the current context.
VG_ILLEGAL_ARGUMENT_ERROR is generated:
  • if glyphCount is zero or a negative value.
  • if the glyphIndices array is null or is not properly aligned.
  • if either of the adjustments_x or adjustments_y arrays are non-null and are not properly aligned.
  • if any of the glyphIndices has not been defined for a given font object.
  • if paintModes is not a valid bitwise OR of values from VG_FILL_PATH or VG_STROKE_PATH, or 0.

Parameters:
font - The font to draw the glyphs from.
glyphCount - The number of glyphs to be drawn.
glyphIndices - The indices of the glyphs to be drawn.
glyphIndicesOffset - The offset into the glyphIndices array.
adjustments_x - The x position glyph adjustment values.
adjustments_xOffset - The offset into the adjustments_x array.
adjustments_y - The y position glyph adjustment values.
adjustments_yOffset - The offset into the adjustments_y array.
paintModes - The paint modes to be used.
allowAutoHinting - true if auto-hinting is allowed; false if not.
Throws:
IllegalArgumentException - if glyphIndices.length - glyphIndicesOffset is less than glyphCount.
IllegalArgumentException - if adjustments_x.length - adjustments_xOffset is less than glyphCount.
IllegalArgumentException - if adjustments_y.length - adjustments_yOffset is less than glyphCount.
Since:
BlackBerry API 6.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.