ppapi/api/trusted/ppb_browser_font_trusted.idl

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines the <code>PPB_BrowserFont_Trusted</code> interface.
   8  */
   9 label Chrome {
  10   M19 = 1.0
  11 };
  12
  13 [assert_size(4)]
  14 enum PP_BrowserFont_Trusted_Family {
  15   /**
  16    * Uses the user's default web page font (normally either the default serif
  17    * or sans serif font).
  18    */
  19   PP_BROWSERFONT_TRUSTED_FAMILY_DEFAULT = 0,
  20
  21   /**
  22    * These families will use the default web page font corresponding to the
  23    * given family.
  24    */
  25   PP_BROWSERFONT_TRUSTED_FAMILY_SERIF = 1,
  26   PP_BROWSERFONT_TRUSTED_FAMILY_SANSSERIF = 2,
  27   PP_BROWSERFONT_TRUSTED_FAMILY_MONOSPACE = 3
  28 };
  29
  30 /**
  31  * Specifies the font weight. Normally users will only use NORMAL or BOLD.
  32  */
  33 [assert_size(4)]
  34 enum PP_BrowserFont_Trusted_Weight {
  35   PP_BROWSERFONT_TRUSTED_WEIGHT_100 = 0,
  36   PP_BROWSERFONT_TRUSTED_WEIGHT_200 = 1,
  37   PP_BROWSERFONT_TRUSTED_WEIGHT_300 = 2,
  38   PP_BROWSERFONT_TRUSTED_WEIGHT_400 = 3,
  39   PP_BROWSERFONT_TRUSTED_WEIGHT_500 = 4,
  40   PP_BROWSERFONT_TRUSTED_WEIGHT_600 = 5,
  41   PP_BROWSERFONT_TRUSTED_WEIGHT_700 = 6,
  42   PP_BROWSERFONT_TRUSTED_WEIGHT_800 = 7,
  43   PP_BROWSERFONT_TRUSTED_WEIGHT_900 = 8,
  44   PP_BROWSERFONT_TRUSTED_WEIGHT_NORMAL =
  45       PP_BROWSERFONT_TRUSTED_WEIGHT_400,
  46   PP_BROWSERFONT_TRUSTED_WEIGHT_BOLD =
  47       PP_BROWSERFONT_TRUSTED_WEIGHT_700
  48 };
  49
  50 [assert_size(48)]
  51 struct PP_BrowserFont_Trusted_Description {
  52   /**
  53    * Font face name as a string. This can also be an undefined var, in which
  54    * case the generic family will be obeyed. If the face is not available on
  55    * the system, the browser will attempt to do font fallback or pick a default
  56    * font.
  57    */
  58   PP_Var face;
  59
  60   /**
  61    * When Create()ing a font and the face is an undefined var, the family
  62    * specifies the generic font family type to use. If the face is specified,
  63    * this will be ignored.
  64    *
  65    * When Describe()ing a font, the family will be the value you passed in when
  66    * the font was created. In other words, if you specify a face name, the
  67    * family will not be updated to reflect whether the font name you requested
  68    * is serif or sans serif.
  69    */
  70   PP_BrowserFont_Trusted_Family family;
  71
  72   /**
  73    * Size in pixels.
  74    *
  75    * You can specify 0 to get the default font size. The default font size
  76    * may vary depending on the requested font. The typical example is that
  77    * the user may have a different font size for the default monospace font to
  78    * give it a similar optical size to the proportionally spaced fonts.
  79    */
  80   uint32_t size;
  81
  82   /**
  83    * Normally you will use either normal or bold.
  84    */
  85   PP_BrowserFont_Trusted_Weight weight;
  86
  87   PP_Bool italic;
  88   PP_Bool small_caps;
  89
  90   /**
  91    * Adjustment to apply to letter and word spacing, respectively. Initialize
  92    * to 0 to get normal spacing. Negative values bring letters/words closer
  93    * together, positive values separate them.
  94    */
  95   int32_t letter_spacing;
  96   int32_t word_spacing;
  97
  98   /**
  99    * Ensure that this struct is 48-bytes wide by padding the end.  In some
 100    * compilers, PP_Var is 8-byte aligned, so those compilers align this struct
 101    * on 8-byte boundaries as well and pad it to 16 bytes even without this
 102    * padding attribute.  This padding makes its size consistent across
 103    * compilers.
 104    */
 105   int32_t padding;
 106 };
 107
 108 [assert_size(20)]
 109 struct PP_BrowserFont_Trusted_Metrics {
 110   int32_t height;
 111   int32_t ascent;
 112   int32_t descent;
 113   int32_t line_spacing;
 114   int32_t x_height;
 115 };
 116
 117 [assert_size(24)]
 118 struct PP_BrowserFont_Trusted_TextRun {
 119   /**
 120    * This var must either be a string or a null/undefined var (which will be
 121    * treated as a 0-length string).
 122    */
 123   PP_Var text;
 124
 125   /**
 126    * Set to PP_TRUE if the text is right-to-left.
 127    */
 128   PP_Bool rtl;
 129
 130   /**
 131    * Set to PP_TRUE to force the directionality of the text regardless of
 132    * content
 133    */
 134   PP_Bool override_direction;
 135 };
 136
 137 /**
 138  * Provides an interface for native browser text rendering.
 139  *
 140  * This API is "trusted" not for security reasons, but because it can not be
 141  * implemented efficiently when running out-of-process in Browser Client. In
 142  * this case, WebKit is in another process and every text call would require a
 143  * synchronous IPC to the renderer. It is, however, available to native
 144  * (non-NaCl) out-of-process PPAPI plugins since WebKit is available in the
 145  * plugin process.
 146  */
 147 interface PPB_BrowserFont_Trusted {
 148   /**
 149    * Returns a list of all available font families on the system. You can use
 150    * this list to decide whether to Create() a font.
 151    *
 152    * The return value will be a single string with null characters delimiting
 153    * the end of each font name. For example: "Arial\0Courier\0Times\0".
 154    *
 155    * Returns an undefined var on failure (this typically means you passed an
 156    * invalid instance).
 157    */
 158   PP_Var GetFontFamilies(
 159       [in] PP_Instance instance);
 160
 161   /**
 162    * Returns a font which best matches the given description. The return value
 163    * will have a non-zero ID on success, or zero on failure.
 164    */
 165   PP_Resource Create(
 166       [in] PP_Instance instance,
 167       [in] PP_BrowserFont_Trusted_Description description);
 168
 169   /**
 170    * Returns PP_TRUE if the given resource is a Font. Returns PP_FALSE if the
 171    * resource is invalid or some type other than a Font.
 172    */
 173   PP_Bool IsFont(
 174       [in] PP_Resource resource);
 175
 176   /**
 177    * Loads the description and metrics of the font into the given structures.
 178    * The description will be different than the description the font was
 179    * created with since it will be filled with the real values from the font
 180    * that was actually selected.
 181    *
 182    * The PP_Var in the description should be of type Void on input. On output,
 183    * this will contain the string and will have a reference count of 1. The
 184    * plugin is responsible for calling Release on this var.
 185    *
 186    * Returns PP_TRUE on success, PP_FALSE if the font is invalid or if the Var
 187    * in the description isn't Null (to prevent leaks).
 188    */
 189   PP_Bool Describe(
 190       [in] PP_Resource font,
 191       [out] PP_BrowserFont_Trusted_Description description,
 192       [out] PP_BrowserFont_Trusted_Metrics metrics);
 193
 194   /**
 195    * Draws the text to the image buffer.
 196    *
 197    * The given point represents the baseline of the left edge of the font,
 198    * regardless of whether it is left-to-right or right-to-left (in the case of
 199    * RTL text, this will actually represent the logical end of the text).
 200    *
 201    * The clip is optional and may be NULL. In this case, the text will be
 202    * clipped to the image.
 203    *
 204    * The image_data_is_opaque flag indicates whether subpixel antialiasing can
 205    * be performed, if it is supported. When the image below the text is
 206    * opaque, subpixel antialiasing is supported and you should set this to
 207    * PP_TRUE to pick up the user's default preferences. If your plugin is
 208    * partially transparent, then subpixel antialiasing is not possible and
 209    * grayscale antialiasing will be used instead (assuming the user has
 210    * antialiasing enabled at all).
 211    */
 212   PP_Bool DrawTextAt(
 213       [in] PP_Resource font,
 214       [in] PP_Resource image_data,
 215       [in] PP_BrowserFont_Trusted_TextRun text,
 216       [in] PP_Point position,
 217       [in] uint32_t color,
 218       [in] PP_Rect clip,
 219       [in] PP_Bool image_data_is_opaque);
 220
 221   /**
 222    * Returns the width of the given string. If the font is invalid or the var
 223    * isn't a valid string, this will return -1.
 224    *
 225    * Note that this function handles complex scripts such as Arabic, combining
 226    * accents, etc. so that adding the width of substrings won't necessarily
 227    * produce the correct width of the entire string.
 228    *
 229    * Returns -1 on failure.
 230    */
 231   int32_t MeasureText(
 232       [in] PP_Resource font,
 233       [in] PP_BrowserFont_Trusted_TextRun text);
 234
 235   /**
 236    * Returns the character at the given pixel X position from the beginning of
 237    * the string. This handles complex scripts such as Arabic, where characters
 238    * may be combined or replaced depending on the context. Returns (uint32)-1
 239    * on failure.
 240    *
 241    * TODO(brettw) this function may be broken. See the CharPosRTL test. It
 242    * seems to tell you "insertion point" rather than painting position. This
 243    * is useful but maybe not what we intended here.
 244    */
 245   uint32_t CharacterOffsetForPixel(
 246       [in] PP_Resource font,
 247       [in] PP_BrowserFont_Trusted_TextRun text,
 248       [in] int32_t pixel_position);
 249
 250   /**
 251    * Returns the horizontal advance to the given character if the string was
 252    * placed at the given position. This handles complex scripts such as Arabic,
 253    * where characters may be combined or replaced depending on context. Returns
 254    * -1 on error.
 255    */
 256   int32_t PixelOffsetForCharacter(
 257       [in] PP_Resource font,
 258       [in] PP_BrowserFont_Trusted_TextRun text,
 259       [in] uint32_t char_offset);
 260 };
 261