src/ppapi/c/trusted/ppb_browser_font_trusted.h

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