src/cairo-font-options.c

   1 /* cairo - a vector graphics library with display and print output
   2  *
   3  * Copyright © 2005 Red Hat Inc.
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it either under the terms of the GNU Lesser General Public
   7  * License version 2.1 as published by the Free Software Foundation
   8  * (the "LGPL") or, at your option, under the terms of the Mozilla
   9  * Public License Version 1.1 (the "MPL"). If you do not alter this
  10  * notice, a recipient may use your version of this file under either
  11  * the MPL or the LGPL.
  12  *
  13  * You should have received a copy of the LGPL along with this library
  14  * in the file COPYING-LGPL-2.1; if not, write to the Free Software
  15  * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
  16  * You should have received a copy of the MPL along with this library
  17  * in the file COPYING-MPL-1.1
  18  *
  19  * The contents of this file are subject to the Mozilla Public License
  20  * Version 1.1 (the "License"); you may not use this file except in
  21  * compliance with the License. You may obtain a copy of the License at
  22  * http://www.mozilla.org/MPL/
  23  *
  24  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
  25  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  26  * the specific language governing rights and limitations.
  27  *
  28  * The Original Code is the cairo graphics library.
  29  *
  30  * The Initial Developer of the Original Code is University of Southern
  31  * California.
  32  *
  33  * Contributor(s):
  34  *      Owen Taylor <otaylor@redhat.com>
  35  */
  36
  37 #include "cairoint.h"
  38 #include "cairo-error-private.h"
  39
  40 /**
  41  * SECTION:cairo-font-options
  42  * @Title: cairo_font_options_t
  43  * @Short_Description: How a font should be rendered
  44  * @See_Also: #cairo_scaled_font_t
  45  *
  46  * The font options specify how fonts should be rendered.  Most of the
  47  * time the font options implied by a surface are just right and do not
  48  * need any changes, but for pixel-based targets tweaking font options
  49  * may result in superior output on a particular display.
  50  **/
  51
  52 static const cairo_font_options_t _cairo_font_options_nil = {
  53     CAIRO_ANTIALIAS_DEFAULT,
  54     CAIRO_SUBPIXEL_ORDER_DEFAULT,
  55     CAIRO_LCD_FILTER_DEFAULT,
  56     CAIRO_HINT_STYLE_DEFAULT,
  57     CAIRO_HINT_METRICS_DEFAULT,
  58     CAIRO_ROUND_GLYPH_POS_DEFAULT
  59 };
  60
  61 /**
  62  * _cairo_font_options_init_default:
  63  * @options: a #cairo_font_options_t
  64  *
  65  * Initializes all fields of the font options object to default values.
  66  **/
  67 void
  68 _cairo_font_options_init_default (cairo_font_options_t *options)
  69 {
  70     options->antialias = CAIRO_ANTIALIAS_DEFAULT;
  71     options->subpixel_order = CAIRO_SUBPIXEL_ORDER_DEFAULT;
  72     options->lcd_filter = CAIRO_LCD_FILTER_DEFAULT;
  73     options->hint_style = CAIRO_HINT_STYLE_DEFAULT;
  74     options->hint_metrics = CAIRO_HINT_METRICS_DEFAULT;
  75     options->round_glyph_positions = CAIRO_ROUND_GLYPH_POS_DEFAULT;
  76     options->color = CAIRO_FONT_COLOR_DEFAULT;
  77 }
  78
  79 void
  80 _cairo_font_options_init_copy (cairo_font_options_t             *options,
  81                                const cairo_font_options_t       *other)
  82 {
  83     options->antialias = other->antialias;
  84     options->subpixel_order = other->subpixel_order;
  85     options->lcd_filter = other->lcd_filter;
  86     options->hint_style = other->hint_style;
  87     options->hint_metrics = other->hint_metrics;
  88     options->round_glyph_positions = other->round_glyph_positions;
  89     options->color = other->color;
  90 }
  91
  92 /**
  93  * cairo_font_options_create:
  94  *
  95  * Allocates a new font options object with all options initialized
  96  *  to default values.
  97  *
  98  * Return value: a newly allocated #cairo_font_options_t. Free with
  99  *   cairo_font_options_destroy(). This function always returns a
 100  *   valid pointer; if memory cannot be allocated, then a special
 101  *   error object is returned where all operations on the object do nothing.
 102  *   You can check for this with cairo_font_options_status().
 103  *
 104  * Since: 1.0
 105  **/
 106 cairo_font_options_t *
 107 cairo_font_options_create (void)
 108 {
 109     cairo_font_options_t *options;
 110
 111     options = _cairo_malloc (sizeof (cairo_font_options_t));
 112     if (!options) {
 113         _cairo_error_throw (CAIRO_STATUS_NO_MEMORY);
 114         return (cairo_font_options_t *) &_cairo_font_options_nil;
 115     }
 116
 117     _cairo_font_options_init_default (options);
 118
 119     return options;
 120 }
 121
 122 /**
 123  * cairo_font_options_copy:
 124  * @original: a #cairo_font_options_t
 125  *
 126  * Allocates a new font options object copying the option values from
 127  *  @original.
 128  *
 129  * Return value: a newly allocated #cairo_font_options_t. Free with
 130  *   cairo_font_options_destroy(). This function always returns a
 131  *   valid pointer; if memory cannot be allocated, then a special
 132  *   error object is returned where all operations on the object do nothing.
 133  *   You can check for this with cairo_font_options_status().
 134  *
 135  * Since: 1.0
 136  **/
 137 cairo_font_options_t *
 138 cairo_font_options_copy (const cairo_font_options_t *original)
 139 {
 140     cairo_font_options_t *options;
 141
 142     if (cairo_font_options_status ((cairo_font_options_t *) original))
 143         return (cairo_font_options_t *) &_cairo_font_options_nil;
 144
 145     options = _cairo_malloc (sizeof (cairo_font_options_t));
 146     if (!options) {
 147         _cairo_error_throw (CAIRO_STATUS_NO_MEMORY);
 148         return (cairo_font_options_t *) &_cairo_font_options_nil;
 149     }
 150
 151     _cairo_font_options_init_copy (options, original);
 152
 153     return options;
 154 }
 155
 156 /**
 157  * cairo_font_options_destroy:
 158  * @options: a #cairo_font_options_t
 159  *
 160  * Destroys a #cairo_font_options_t object created with
 161  * cairo_font_options_create() or cairo_font_options_copy().
 162  *
 163  * Since: 1.0
 164  **/
 165 void
 166 cairo_font_options_destroy (cairo_font_options_t *options)
 167 {
 168     if (cairo_font_options_status (options))
 169         return;
 170
 171     free (options);
 172 }
 173
 174 /**
 175  * cairo_font_options_status:
 176  * @options: a #cairo_font_options_t
 177  *
 178  * Checks whether an error has previously occurred for this
 179  * font options object
 180  *
 181  * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
 182  *
 183  * Since: 1.0
 184  **/
 185 cairo_status_t
 186 cairo_font_options_status (cairo_font_options_t *options)
 187 {
 188     if (options == NULL)
 189         return CAIRO_STATUS_NULL_POINTER;
 190     else if (options == (cairo_font_options_t *) &_cairo_font_options_nil)
 191         return CAIRO_STATUS_NO_MEMORY;
 192     else
 193         return CAIRO_STATUS_SUCCESS;
 194 }
 195 slim_hidden_def (cairo_font_options_status);
 196
 197 /**
 198  * cairo_font_options_merge:
 199  * @options: a #cairo_font_options_t
 200  * @other: another #cairo_font_options_t
 201  *
 202  * Merges non-default options from @other into @options, replacing
 203  * existing values. This operation can be thought of as somewhat
 204  * similar to compositing @other onto @options with the operation
 205  * of %CAIRO_OPERATOR_OVER.
 206  *
 207  * Since: 1.0
 208  **/
 209 void
 210 cairo_font_options_merge (cairo_font_options_t       *options,
 211                           const cairo_font_options_t *other)
 212 {
 213     if (cairo_font_options_status (options))
 214         return;
 215
 216     if (cairo_font_options_status ((cairo_font_options_t *) other))
 217         return;
 218
 219     if (other->antialias != CAIRO_ANTIALIAS_DEFAULT)
 220         options->antialias = other->antialias;
 221     if (other->subpixel_order != CAIRO_SUBPIXEL_ORDER_DEFAULT)
 222         options->subpixel_order = other->subpixel_order;
 223     if (other->lcd_filter != CAIRO_LCD_FILTER_DEFAULT)
 224         options->lcd_filter = other->lcd_filter;
 225     if (other->hint_style != CAIRO_HINT_STYLE_DEFAULT)
 226         options->hint_style = other->hint_style;
 227     if (other->hint_metrics != CAIRO_HINT_METRICS_DEFAULT)
 228         options->hint_metrics = other->hint_metrics;
 229     if (other->round_glyph_positions != CAIRO_ROUND_GLYPH_POS_DEFAULT)
 230         options->round_glyph_positions = other->round_glyph_positions;
 231     if (other->color != CAIRO_FONT_COLOR_DEFAULT)
 232         options->color = other->color;
 233 }
 234 slim_hidden_def (cairo_font_options_merge);
 235
 236 /**
 237  * cairo_font_options_equal:
 238  * @options: a #cairo_font_options_t
 239  * @other: another #cairo_font_options_t
 240  *
 241  * Compares two font options objects for equality.
 242  *
 243  * Return value: %TRUE if all fields of the two font options objects match.
 244  *      Note that this function will return %FALSE if either object is in
 245  *      error.
 246  *
 247  * Since: 1.0
 248  **/
 249 cairo_bool_t
 250 cairo_font_options_equal (const cairo_font_options_t *options,
 251                           const cairo_font_options_t *other)
 252 {
 253     if (cairo_font_options_status ((cairo_font_options_t *) options))
 254         return FALSE;
 255     if (cairo_font_options_status ((cairo_font_options_t *) other))
 256         return FALSE;
 257
 258     if (options == other)
 259         return TRUE;
 260
 261     return (options->antialias == other->antialias &&
 262             options->subpixel_order == other->subpixel_order &&
 263             options->lcd_filter == other->lcd_filter &&
 264             options->hint_style == other->hint_style &&
 265             options->hint_metrics == other->hint_metrics &&
 266             options->round_glyph_positions == other->round_glyph_positions &&
 267             options->color == other->color);
 268 }
 269 slim_hidden_def (cairo_font_options_equal);
 270
 271 /**
 272  * cairo_font_options_hash:
 273  * @options: a #cairo_font_options_t
 274  *
 275  * Compute a hash for the font options object; this value will
 276  * be useful when storing an object containing a #cairo_font_options_t
 277  * in a hash table.
 278  *
 279  * Return value: the hash value for the font options object.
 280  *   The return value can be cast to a 32-bit type if a
 281  *   32-bit hash value is needed.
 282  *
 283  * Since: 1.0
 284  **/
 285 unsigned long
 286 cairo_font_options_hash (const cairo_font_options_t *options)
 287 {
 288     if (cairo_font_options_status ((cairo_font_options_t *) options))
 289         options = &_cairo_font_options_nil; /* force default values */
 290
 291     return ((options->antialias) |
 292             (options->subpixel_order << 4) |
 293             (options->lcd_filter << 8) |
 294             (options->hint_style << 12) |
 295             (options->hint_metrics << 16) |
 296             (options->color << 20));
 297 }
 298 slim_hidden_def (cairo_font_options_hash);
 299
 300 /**
 301  * cairo_font_options_set_antialias:
 302  * @options: a #cairo_font_options_t
 303  * @antialias: the new antialiasing mode
 304  *
 305  * Sets the antialiasing mode for the font options object. This
 306  * specifies the type of antialiasing to do when rendering text.
 307  *
 308  * Since: 1.0
 309  **/
 310 void
 311 cairo_font_options_set_antialias (cairo_font_options_t *options,
 312                                   cairo_antialias_t     antialias)
 313 {
 314     if (cairo_font_options_status (options))
 315         return;
 316
 317     options->antialias = antialias;
 318 }
 319 slim_hidden_def (cairo_font_options_set_antialias);
 320
 321 /**
 322  * cairo_font_options_get_antialias:
 323  * @options: a #cairo_font_options_t
 324  *
 325  * Gets the antialiasing mode for the font options object.
 326  *
 327  * Return value: the antialiasing mode
 328  *
 329  * Since: 1.0
 330  **/
 331 cairo_antialias_t
 332 cairo_font_options_get_antialias (const cairo_font_options_t *options)
 333 {
 334     if (cairo_font_options_status ((cairo_font_options_t *) options))
 335         return CAIRO_ANTIALIAS_DEFAULT;
 336
 337     return options->antialias;
 338 }
 339
 340 /**
 341  * cairo_font_options_set_subpixel_order:
 342  * @options: a #cairo_font_options_t
 343  * @subpixel_order: the new subpixel order
 344  *
 345  * Sets the subpixel order for the font options object. The subpixel
 346  * order specifies the order of color elements within each pixel on
 347  * the display device when rendering with an antialiasing mode of
 348  * %CAIRO_ANTIALIAS_SUBPIXEL. See the documentation for
 349  * #cairo_subpixel_order_t for full details.
 350  *
 351  * Since: 1.0
 352  **/
 353 void
 354 cairo_font_options_set_subpixel_order (cairo_font_options_t   *options,
 355                                        cairo_subpixel_order_t  subpixel_order)
 356 {
 357     if (cairo_font_options_status (options))
 358         return;
 359
 360     options->subpixel_order = subpixel_order;
 361 }
 362 slim_hidden_def (cairo_font_options_set_subpixel_order);
 363
 364 /**
 365  * cairo_font_options_get_subpixel_order:
 366  * @options: a #cairo_font_options_t
 367  *
 368  * Gets the subpixel order for the font options object.
 369  * See the documentation for #cairo_subpixel_order_t for full details.
 370  *
 371  * Return value: the subpixel order for the font options object
 372  *
 373  * Since: 1.0
 374  **/
 375 cairo_subpixel_order_t
 376 cairo_font_options_get_subpixel_order (const cairo_font_options_t *options)
 377 {
 378     if (cairo_font_options_status ((cairo_font_options_t *) options))
 379         return CAIRO_SUBPIXEL_ORDER_DEFAULT;
 380
 381     return options->subpixel_order;
 382 }
 383
 384 /**
 385  * _cairo_font_options_set_lcd_filter:
 386  * @options: a #cairo_font_options_t
 387  * @lcd_filter: the new LCD filter
 388  *
 389  * Sets the LCD filter for the font options object. The LCD filter
 390  * specifies how pixels are filtered when rendered with an antialiasing
 391  * mode of %CAIRO_ANTIALIAS_SUBPIXEL. See the documentation for
 392  * #cairo_lcd_filter_t for full details.
 393  **/
 394 void
 395 _cairo_font_options_set_lcd_filter (cairo_font_options_t *options,
 396                                     cairo_lcd_filter_t    lcd_filter)
 397 {
 398     if (cairo_font_options_status (options))
 399         return;
 400
 401     options->lcd_filter = lcd_filter;
 402 }
 403
 404 /**
 405  * _cairo_font_options_get_lcd_filter:
 406  * @options: a #cairo_font_options_t
 407  *
 408  * Gets the LCD filter for the font options object.
 409  * See the documentation for #cairo_lcd_filter_t for full details.
 410  *
 411  * Return value: the LCD filter for the font options object
 412  **/
 413 cairo_lcd_filter_t
 414 _cairo_font_options_get_lcd_filter (const cairo_font_options_t *options)
 415 {
 416     if (cairo_font_options_status ((cairo_font_options_t *) options))
 417         return CAIRO_LCD_FILTER_DEFAULT;
 418
 419     return options->lcd_filter;
 420 }
 421
 422 /**
 423  * _cairo_font_options_set_round_glyph_positions:
 424  * @options: a #cairo_font_options_t
 425  * @round: the new rounding value
 426  *
 427  * Sets the rounding options for the font options object. If rounding is set, a
 428  * glyph's position will be rounded to integer values.
 429  **/
 430 void
 431 _cairo_font_options_set_round_glyph_positions (cairo_font_options_t *options,
 432                                                cairo_round_glyph_positions_t  round)
 433 {
 434     if (cairo_font_options_status (options))
 435         return;
 436
 437     options->round_glyph_positions = round;
 438 }
 439
 440 /**
 441  * _cairo_font_options_get_round_glyph_positions:
 442  * @options: a #cairo_font_options_t
 443  *
 444  * Gets the glyph position rounding option for the font options object.
 445  *
 446  * Return value: The round glyph posistions flag for the font options object.
 447  **/
 448 cairo_round_glyph_positions_t
 449 _cairo_font_options_get_round_glyph_positions (const cairo_font_options_t *options)
 450 {
 451     if (cairo_font_options_status ((cairo_font_options_t *) options))
 452         return CAIRO_ROUND_GLYPH_POS_DEFAULT;
 453
 454     return options->round_glyph_positions;
 455 }
 456
 457 /**
 458  * cairo_font_options_set_hint_style:
 459  * @options: a #cairo_font_options_t
 460  * @hint_style: the new hint style
 461  *
 462  * Sets the hint style for font outlines for the font options object.
 463  * This controls whether to fit font outlines to the pixel grid,
 464  * and if so, whether to optimize for fidelity or contrast.
 465  * See the documentation for #cairo_hint_style_t for full details.
 466  *
 467  * Since: 1.0
 468  **/
 469 void
 470 cairo_font_options_set_hint_style (cairo_font_options_t *options,
 471                                    cairo_hint_style_t    hint_style)
 472 {
 473     if (cairo_font_options_status (options))
 474         return;
 475
 476     options->hint_style = hint_style;
 477 }
 478 slim_hidden_def (cairo_font_options_set_hint_style);
 479
 480 /**
 481  * cairo_font_options_get_hint_style:
 482  * @options: a #cairo_font_options_t
 483  *
 484  * Gets the hint style for font outlines for the font options object.
 485  * See the documentation for #cairo_hint_style_t for full details.
 486  *
 487  * Return value: the hint style for the font options object
 488  *
 489  * Since: 1.0
 490  **/
 491 cairo_hint_style_t
 492 cairo_font_options_get_hint_style (const cairo_font_options_t *options)
 493 {
 494     if (cairo_font_options_status ((cairo_font_options_t *) options))
 495         return CAIRO_HINT_STYLE_DEFAULT;
 496
 497     return options->hint_style;
 498 }
 499
 500 /**
 501  * cairo_font_options_set_hint_metrics:
 502  * @options: a #cairo_font_options_t
 503  * @hint_metrics: the new metrics hinting mode
 504  *
 505  * Sets the metrics hinting mode for the font options object. This
 506  * controls whether metrics are quantized to integer values in
 507  * device units.
 508  * See the documentation for #cairo_hint_metrics_t for full details.
 509  *
 510  * Since: 1.0
 511  **/
 512 void
 513 cairo_font_options_set_hint_metrics (cairo_font_options_t *options,
 514                                      cairo_hint_metrics_t  hint_metrics)
 515 {
 516     if (cairo_font_options_status (options))
 517         return;
 518
 519     options->hint_metrics = hint_metrics;
 520 }
 521 slim_hidden_def (cairo_font_options_set_hint_metrics);
 522
 523 /**
 524  * cairo_font_options_get_hint_metrics:
 525  * @options: a #cairo_font_options_t
 526  *
 527  * Gets the metrics hinting mode for the font options object.
 528  * See the documentation for #cairo_hint_metrics_t for full details.
 529  *
 530  * Return value: the metrics hinting mode for the font options object
 531  *
 532  * Since: 1.0
 533  **/
 534 cairo_hint_metrics_t
 535 cairo_font_options_get_hint_metrics (const cairo_font_options_t *options)
 536 {
 537     if (cairo_font_options_status ((cairo_font_options_t *) options))
 538         return CAIRO_HINT_METRICS_DEFAULT;
 539
 540     return options->hint_metrics;
 541 }
 542
 543 void
 544 cairo_font_options_set_font_color (cairo_font_options_t *options,
 545                                    cairo_font_color_t  font_color)
 546 {
 547     if (cairo_font_options_status (options))
 548         return;
 549
 550     options->color = font_color;
 551 }
 552 slim_hidden_def (cairo_font_options_set_font_color);
 553
 554 cairo_font_color_t
 555 cairo_font_options_get_font_color (const cairo_font_options_t *options)
 556 {
 557     if (cairo_font_options_status ((cairo_font_options_t *) options))
 558         return CAIRO_FONT_COLOR_DEFAULT;
 559
 560     return options->color;
 561 }