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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 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
  39 static const cairo_font_options_t _cairo_font_options_nil = {
  40     CAIRO_ANTIALIAS_DEFAULT,
  41     CAIRO_SUBPIXEL_ORDER_DEFAULT,
  42     CAIRO_HINT_STYLE_DEFAULT,
  43     CAIRO_HINT_METRICS_DEFAULT
  44 };
  45
  46 /**
  47  * _cairo_font_options_init_default:
  48  * @options: a #cairo_font_options_t
  49  *
  50  * Initializes all fields of the font options object to default values.
  51  **/
  52 void
  53 _cairo_font_options_init_default (cairo_font_options_t *options)
  54 {
  55     options->antialias = CAIRO_ANTIALIAS_DEFAULT;
  56     options->subpixel_order = CAIRO_SUBPIXEL_ORDER_DEFAULT;
  57     options->hint_style = CAIRO_HINT_STYLE_DEFAULT;
  58     options->hint_metrics = CAIRO_HINT_METRICS_DEFAULT;
  59 }
  60
  61 void
  62 _cairo_font_options_init_copy (cairo_font_options_t             *options,
  63                                const cairo_font_options_t       *other)
  64 {
  65     options->antialias = other->antialias;
  66     options->subpixel_order = other->subpixel_order;
  67     options->hint_style = other->hint_style;
  68     options->hint_metrics = other->hint_metrics;
  69 }
  70
  71 /**
  72  * cairo_font_options_create:
  73  *
  74  * Allocates a new font options object with all options initialized
  75  *  to default values.
  76  *
  77  * Return value: a newly allocated #cairo_font_options_t. Free with
  78  *   cairo_font_options_destroy(). This function always returns a
  79  *   valid pointer; if memory cannot be allocated, then a special
  80  *   error object is returned where all operations on the object do nothing.
  81  *   You can check for this with cairo_font_options_status().
  82  **/
  83 cairo_font_options_t *
  84 cairo_font_options_create (void)
  85 {
  86     cairo_font_options_t *options;
  87
  88     options = malloc (sizeof (cairo_font_options_t));
  89     if (!options) {
  90         _cairo_error_throw (CAIRO_STATUS_NO_MEMORY);
  91         return (cairo_font_options_t *) &_cairo_font_options_nil;
  92     }
  93
  94     _cairo_font_options_init_default (options);
  95
  96     return options;
  97 }
  98
  99 /**
 100  * cairo_font_options_copy:
 101  * @original: a #cairo_font_options_t
 102  *
 103  * Allocates a new font options object copying the option values from
 104  *  @original.
 105  *
 106  * Return value: a newly allocated #cairo_font_options_t. Free with
 107  *   cairo_font_options_destroy(). This function always returns a
 108  *   valid pointer; if memory cannot be allocated, then a special
 109  *   error object is returned where all operations on the object do nothing.
 110  *   You can check for this with cairo_font_options_status().
 111  **/
 112 cairo_font_options_t *
 113 cairo_font_options_copy (const cairo_font_options_t *original)
 114 {
 115     cairo_font_options_t *options;
 116
 117     if (cairo_font_options_status ((cairo_font_options_t *) original))
 118         return (cairo_font_options_t *) &_cairo_font_options_nil;
 119
 120     options = malloc (sizeof (cairo_font_options_t));
 121     if (!options) {
 122         _cairo_error_throw (CAIRO_STATUS_NO_MEMORY);
 123         return (cairo_font_options_t *) &_cairo_font_options_nil;
 124     }
 125
 126     _cairo_font_options_init_copy (options, original);
 127
 128     return options;
 129 }
 130
 131 /**
 132  * cairo_font_options_destroy:
 133  * @options: a #cairo_font_options_t
 134  *
 135  * Destroys a #cairo_font_options_t object created with
 136  * cairo_font_options_create() or cairo_font_options_copy().
 137  **/
 138 void
 139 cairo_font_options_destroy (cairo_font_options_t *options)
 140 {
 141     if (cairo_font_options_status (options))
 142         return;
 143
 144     free (options);
 145 }
 146
 147 /**
 148  * cairo_font_options_status:
 149  * @options: a #cairo_font_options_t
 150  *
 151  * Checks whether an error has previously occurred for this
 152  * font options object
 153  *
 154  * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
 155  **/
 156 cairo_status_t
 157 cairo_font_options_status (cairo_font_options_t *options)
 158 {
 159     if (options == NULL)
 160         return CAIRO_STATUS_NULL_POINTER;
 161     else if (options == (cairo_font_options_t *) &_cairo_font_options_nil)
 162         return CAIRO_STATUS_NO_MEMORY;
 163     else
 164         return CAIRO_STATUS_SUCCESS;
 165 }
 166 slim_hidden_def (cairo_font_options_status);
 167
 168 /**
 169  * cairo_font_options_merge:
 170  * @options: a #cairo_font_options_t
 171  * @other: another #cairo_font_options_t
 172  *
 173  * Merges non-default options from @other into @options, replacing
 174  * existing values. This operation can be thought of as somewhat
 175  * similar to compositing @other onto @options with the operation
 176  * of %CAIRO_OPERATION_OVER.
 177  **/
 178 void
 179 cairo_font_options_merge (cairo_font_options_t       *options,
 180                           const cairo_font_options_t *other)
 181 {
 182     if (cairo_font_options_status (options))
 183         return;
 184
 185     if (cairo_font_options_status ((cairo_font_options_t *) other))
 186         return;
 187
 188     if (other->antialias != CAIRO_ANTIALIAS_DEFAULT)
 189         options->antialias = other->antialias;
 190     if (other->subpixel_order != CAIRO_SUBPIXEL_ORDER_DEFAULT)
 191         options->subpixel_order = other->subpixel_order;
 192     if (other->hint_style != CAIRO_HINT_STYLE_DEFAULT)
 193         options->hint_style = other->hint_style;
 194     if (other->hint_metrics != CAIRO_HINT_METRICS_DEFAULT)
 195         options->hint_metrics = other->hint_metrics;
 196 }
 197 slim_hidden_def (cairo_font_options_merge);
 198
 199 /**
 200  * cairo_font_options_equal:
 201  * @options: a #cairo_font_options_t
 202  * @other: another #cairo_font_options_t
 203  *
 204  * Compares two font options objects for equality.
 205  *
 206  * Return value: %TRUE if all fields of the two font options objects match.
 207  *      Note that this function will return %FALSE if either object is in
 208  *      error.
 209  **/
 210 cairo_bool_t
 211 cairo_font_options_equal (const cairo_font_options_t *options,
 212                           const cairo_font_options_t *other)
 213 {
 214     if (cairo_font_options_status ((cairo_font_options_t *) options))
 215         return FALSE;
 216     if (cairo_font_options_status ((cairo_font_options_t *) other))
 217         return FALSE;
 218
 219     if (options == other)
 220         return TRUE;
 221
 222     return (options->antialias == other->antialias &&
 223             options->subpixel_order == other->subpixel_order &&
 224             options->hint_style == other->hint_style &&
 225             options->hint_metrics == other->hint_metrics);
 226 }
 227 slim_hidden_def (cairo_font_options_equal);
 228
 229 /**
 230  * cairo_font_options_hash:
 231  * @options: a #cairo_font_options_t
 232  *
 233  * Compute a hash for the font options object; this value will
 234  * be useful when storing an object containing a #cairo_font_options_t
 235  * in a hash table.
 236  *
 237  * Return value: the hash value for the font options object.
 238  *   The return value can be cast to a 32-bit type if a
 239  *   32-bit hash value is needed.
 240  **/
 241 unsigned long
 242 cairo_font_options_hash (const cairo_font_options_t *options)
 243 {
 244     if (cairo_font_options_status ((cairo_font_options_t *) options))
 245         options = &_cairo_font_options_nil; /* force default values */
 246
 247     return ((options->antialias) |
 248             (options->subpixel_order << 4) |
 249             (options->hint_style << 8) |
 250             (options->hint_metrics << 16));
 251 }
 252 slim_hidden_def (cairo_font_options_hash);
 253
 254 /**
 255  * cairo_font_options_set_antialias:
 256  * @options: a #cairo_font_options_t
 257  * @antialias: the new antialiasing mode
 258  *
 259  * Sets the antialiasing mode for the font options object. This
 260  * specifies the type of antialiasing to do when rendering text.
 261  **/
 262 void
 263 cairo_font_options_set_antialias (cairo_font_options_t *options,
 264                                   cairo_antialias_t     antialias)
 265 {
 266     if (cairo_font_options_status (options))
 267         return;
 268
 269     options->antialias = antialias;
 270 }
 271 slim_hidden_def (cairo_font_options_set_antialias);
 272
 273 /**
 274  * cairo_font_options_get_antialias:
 275  * @options: a #cairo_font_options_t
 276  *
 277  * Gets the antialiasing mode for the font options object.
 278  *
 279  * Return value: the antialiasing mode
 280  **/
 281 cairo_antialias_t
 282 cairo_font_options_get_antialias (const cairo_font_options_t *options)
 283 {
 284     if (cairo_font_options_status ((cairo_font_options_t *) options))
 285         return CAIRO_ANTIALIAS_DEFAULT;
 286
 287     return options->antialias;
 288 }
 289
 290 /**
 291  * cairo_font_options_set_subpixel_order:
 292  * @options: a #cairo_font_options_t
 293  * @subpixel_order: the new subpixel order
 294  *
 295  * Sets the subpixel order for the font options object. The subpixel
 296  * order specifies the order of color elements within each pixel on
 297  * the display device when rendering with an antialiasing mode of
 298  * %CAIRO_ANTIALIAS_SUBPIXEL. See the documentation for
 299  * #cairo_subpixel_order_t for full details.
 300  **/
 301 void
 302 cairo_font_options_set_subpixel_order (cairo_font_options_t   *options,
 303                                        cairo_subpixel_order_t  subpixel_order)
 304 {
 305     if (cairo_font_options_status (options))
 306         return;
 307
 308     options->subpixel_order = subpixel_order;
 309 }
 310 slim_hidden_def (cairo_font_options_set_subpixel_order);
 311
 312 /**
 313  * cairo_font_options_get_subpixel_order:
 314  * @options: a #cairo_font_options_t
 315  *
 316  * Gets the subpixel order for the font options object.
 317  * See the documentation for #cairo_subpixel_order_t for full details.
 318  *
 319  * Return value: the subpixel order for the font options object
 320  **/
 321 cairo_subpixel_order_t
 322 cairo_font_options_get_subpixel_order (const cairo_font_options_t *options)
 323 {
 324     if (cairo_font_options_status ((cairo_font_options_t *) options))
 325         return CAIRO_SUBPIXEL_ORDER_DEFAULT;
 326
 327     return options->subpixel_order;
 328 }
 329
 330 /**
 331  * cairo_font_options_set_hint_style:
 332  * @options: a #cairo_font_options_t
 333  * @hint_style: the new hint style
 334  *
 335  * Sets the hint style for font outlines for the font options object.
 336  * This controls whether to fit font outlines to the pixel grid,
 337  * and if so, whether to optimize for fidelity or contrast.
 338  * See the documentation for #cairo_hint_style_t for full details.
 339  **/
 340 void
 341 cairo_font_options_set_hint_style (cairo_font_options_t *options,
 342                                    cairo_hint_style_t    hint_style)
 343 {
 344     if (cairo_font_options_status (options))
 345         return;
 346
 347     options->hint_style = hint_style;
 348 }
 349 slim_hidden_def (cairo_font_options_set_hint_style);
 350
 351 /**
 352  * cairo_font_options_get_hint_style:
 353  * @options: a #cairo_font_options_t
 354  *
 355  * Gets the hint style for font outlines for the font options object.
 356  * See the documentation for #cairo_hint_style_t for full details.
 357  *
 358  * Return value: the hint style for the font options object
 359  **/
 360 cairo_hint_style_t
 361 cairo_font_options_get_hint_style (const cairo_font_options_t *options)
 362 {
 363     if (cairo_font_options_status ((cairo_font_options_t *) options))
 364         return CAIRO_HINT_STYLE_DEFAULT;
 365
 366     return options->hint_style;
 367 }
 368
 369 /**
 370  * cairo_font_options_set_hint_metrics:
 371  * @options: a #cairo_font_options_t
 372  * @hint_metrics: the new metrics hinting mode
 373  *
 374  * Sets the metrics hinting mode for the font options object. This
 375  * controls whether metrics are quantized to integer values in
 376  * device units.
 377  * See the documentation for #cairo_hint_metrics_t for full details.
 378  **/
 379 void
 380 cairo_font_options_set_hint_metrics (cairo_font_options_t *options,
 381                                      cairo_hint_metrics_t  hint_metrics)
 382 {
 383     if (cairo_font_options_status (options))
 384         return;
 385
 386     options->hint_metrics = hint_metrics;
 387 }
 388 slim_hidden_def (cairo_font_options_set_hint_metrics);
 389
 390 /**
 391  * cairo_font_options_get_hint_metrics:
 392  * @options: a #cairo_font_options_t
 393  *
 394  * Gets the metrics hinting mode for the font options object.
 395  * See the documentation for #cairo_hint_metrics_t for full details.
 396  *
 397  * Return value: the metrics hinting mode for the font options object
 398  **/
 399 cairo_hint_metrics_t
 400 cairo_font_options_get_hint_metrics (const cairo_font_options_t *options)
 401 {
 402     if (cairo_font_options_status ((cairo_font_options_t *) options))
 403         return CAIRO_HINT_METRICS_DEFAULT;
 404
 405     return options->hint_metrics;
 406 }