|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface VG11
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.
VGUtils,
EGL12| 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. |
|
| 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 |
|
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. |
|
| Field Detail |
|---|
static final int OPENVG_VERSION_1_1
static final int VG_COLOR_TRANSFORM
static final int VG_COLOR_TRANSFORM_VALUES
static final int VG_GLYPH_ORIGIN
static final int VG_MATRIX_GLYPH_USER_TO_SURFACE
static final int VG_A_1
static final int VG_A_4
static final int VG_FONT_NUM_GLYPHS
| Method Detail |
|---|
void vgRenderToMask(int path,
int paintModes,
int operation)
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.
VG_BAD_HANDLE_ERROR is generated:
path is not a valid handle, or is not shared with the current context.VG_ILLEGAL_ARGUMENT_ERROR is generated:
VG_FILL_PATH or VG_STROKE_PATH.VG_ILLEGAL_ARGUMENT_ERROR is generated:
operation is not VG_CLEAR_MASK, VG_FILL_MASK
VG_SET_MASK, VG_UNION_MASK, VG_INTERSECT_MASK or
VG_SUBTRACT_MASK.
path - The associate path to render the mask on.paintModes - The paintModes to be used.operation - Operation used to modify the alpha masks.VG10.vgMask(int, int, int, int, int, int)
int vgCreateMaskLayer(int width,
int height)
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.
VG_ILLEGAL_ARGUMENT_ERROR is generated:
width or height is less than or equal to 0
width - The mask layer width.height - The mask layer height.
VGMaskLayer handle to the newly created mask layer; VG_INVALID_HANDLE if an error occurs.void vgDestroyMaskLayer(int maskLayer)
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.
VG_BAD_HANDLE_ERROR is generated:
maskLayer is not a valid mask handle.
maskLayer - The mask layer to be destroyed.
void vgFillMaskLayer(int maskLayer,
int x,
int y,
int width,
int height,
float value)
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:
- if
value is less than 0 or greater than 1.
- if
x or
y is less than 0
width or height is less than or equal to 0x + width is greater than width of mask.y + height is greater than height of mask.
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.
void vgCopyMask(int maskLayer,
int dx,
int dy,
int sx,
int sy,
int width,
int height)
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.
VG_BAD_HANDLE_ERROR is generated:
maskLayer is not a valid mask handle.VG_ILLEGAL_ARGUMENT_ERROR is generated:
width or height is less than or equal to 0maskLayer is not compatible with the current surface mask
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.int vgCreateFont(int glyphCapacityHint)
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.
VG_ILLEGAL_ARGUMENT_ERROR is generated:
glyphCapacityHint is negative.
glyphCapacityHint - The font glyph capacity or 0 if unknown.
VGFont handle to the newly created font; VG_INVALID_HANDLE if an error occurs.void vgDestroyFont(int font)
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.
VG_BAD_HANDLE_ERROR is generated:
font is not a valid font handle, or is not shared with the current context.
font - The font to be destroyed.
void vgSetGlyphToPath(int font,
int glyphIndex,
int path,
boolean isHinted,
float[] glyphOrigin,
int glyphOriginOffset,
float[] escapement,
int escapementOffset)
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 <space>
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.
VG_BAD_HANDLE_ERROR is generated:
font is not a valid font handle, or is not shared with the current context.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:
glyphOrigin or escapement is null or is not properly aligned.
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.
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.
void vgSetGlyphToImage(int font,
int glyphIndex,
int image,
float[] glyphOrigin,
int glyphOriginOffset,
float[] escapement,
int escapementOffset)
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 <space> 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 image to.glyphIndex - The glyph to set the image for.image - The image to be used as the glyphglyphOrigin - 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
void vgClearGlyph(int font,
int glyphIndex)
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.
VG_BAD_HANDLE_ERROR is generated:
font is not a valid font handle, or is not shared with the current context.VG_ILLEGAL_ARGUMENT_ERROR is generated:
glyphIndex is not defined for the font.
font - The font to clear the glyph index on.glyphIndex - The glyph index to be cleared.
void vgDrawGlyph(int font,
int glyphIndex,
int paintModes,
boolean allowAutoHinting)
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.
VG_BAD_HANDLE_ERROR is generated:
font is not a valid font handle,
or is not shared with the current context.VG_ILLEGAL_ARGUMENT_ERROR is generated:
VG_FILL_PATH or VG_STROKE_PATH.
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.
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)
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.
VG_BAD_HANDLE_ERROR is generated:
font is not a valid font handle, or is not shared with the current context.VG_ILLEGAL_ARGUMENT_ERROR is generated:
glyphCount is zero or a negative value.glyphIndices array is null or is not properly aligned.adjustments_x or adjustments_y arrays are non-null and are not properly aligned.VG_FILL_PATH or VG_STROKE_PATH, or 0.
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.
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.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal