1 /* cairo - a vector graphics library with display and print output
3 * Copyright © 2005 Red Hat Inc.
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.
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
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/
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.
28 * The Original Code is the cairo graphics library.
30 * The Initial Developer of the Original Code is University of Southern
34 * Owen Taylor <otaylor@redhat.com>
38 #include "cairo-error-private.h"
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
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.
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
62 * _cairo_font_options_init_default:
63 * @options: a #cairo_font_options_t
65 * Initializes all fields of the font options object to default values.
68 _cairo_font_options_init_default (cairo_font_options_t
*options
)
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
;
79 _cairo_font_options_init_copy (cairo_font_options_t
*options
,
80 const cairo_font_options_t
*other
)
82 options
->antialias
= other
->antialias
;
83 options
->subpixel_order
= other
->subpixel_order
;
84 options
->lcd_filter
= other
->lcd_filter
;
85 options
->hint_style
= other
->hint_style
;
86 options
->hint_metrics
= other
->hint_metrics
;
87 options
->round_glyph_positions
= other
->round_glyph_positions
;
91 * cairo_font_options_create:
93 * Allocates a new font options object with all options initialized
96 * Return value: a newly allocated #cairo_font_options_t. Free with
97 * cairo_font_options_destroy(). This function always returns a
98 * valid pointer; if memory cannot be allocated, then a special
99 * error object is returned where all operations on the object do nothing.
100 * You can check for this with cairo_font_options_status().
104 cairo_font_options_t
*
105 cairo_font_options_create (void)
107 cairo_font_options_t
*options
;
109 options
= malloc (sizeof (cairo_font_options_t
));
111 _cairo_error_throw (CAIRO_STATUS_NO_MEMORY
);
112 return (cairo_font_options_t
*) &_cairo_font_options_nil
;
115 _cairo_font_options_init_default (options
);
121 * cairo_font_options_copy:
122 * @original: a #cairo_font_options_t
124 * Allocates a new font options object copying the option values from
127 * Return value: a newly allocated #cairo_font_options_t. Free with
128 * cairo_font_options_destroy(). This function always returns a
129 * valid pointer; if memory cannot be allocated, then a special
130 * error object is returned where all operations on the object do nothing.
131 * You can check for this with cairo_font_options_status().
135 cairo_font_options_t
*
136 cairo_font_options_copy (const cairo_font_options_t
*original
)
138 cairo_font_options_t
*options
;
140 if (cairo_font_options_status ((cairo_font_options_t
*) original
))
141 return (cairo_font_options_t
*) &_cairo_font_options_nil
;
143 options
= malloc (sizeof (cairo_font_options_t
));
145 _cairo_error_throw (CAIRO_STATUS_NO_MEMORY
);
146 return (cairo_font_options_t
*) &_cairo_font_options_nil
;
149 _cairo_font_options_init_copy (options
, original
);
155 * cairo_font_options_destroy:
156 * @options: a #cairo_font_options_t
158 * Destroys a #cairo_font_options_t object created with
159 * cairo_font_options_create() or cairo_font_options_copy().
164 cairo_font_options_destroy (cairo_font_options_t
*options
)
166 if (cairo_font_options_status (options
))
173 * cairo_font_options_status:
174 * @options: a #cairo_font_options_t
176 * Checks whether an error has previously occurred for this
177 * font options object
179 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
184 cairo_font_options_status (cairo_font_options_t
*options
)
187 return CAIRO_STATUS_NULL_POINTER
;
188 else if (options
== (cairo_font_options_t
*) &_cairo_font_options_nil
)
189 return CAIRO_STATUS_NO_MEMORY
;
191 return CAIRO_STATUS_SUCCESS
;
193 slim_hidden_def (cairo_font_options_status
);
196 * cairo_font_options_merge:
197 * @options: a #cairo_font_options_t
198 * @other: another #cairo_font_options_t
200 * Merges non-default options from @other into @options, replacing
201 * existing values. This operation can be thought of as somewhat
202 * similar to compositing @other onto @options with the operation
203 * of %CAIRO_OPERATOR_OVER.
208 cairo_font_options_merge (cairo_font_options_t
*options
,
209 const cairo_font_options_t
*other
)
211 if (cairo_font_options_status (options
))
214 if (cairo_font_options_status ((cairo_font_options_t
*) other
))
217 if (other
->antialias
!= CAIRO_ANTIALIAS_DEFAULT
)
218 options
->antialias
= other
->antialias
;
219 if (other
->subpixel_order
!= CAIRO_SUBPIXEL_ORDER_DEFAULT
)
220 options
->subpixel_order
= other
->subpixel_order
;
221 if (other
->lcd_filter
!= CAIRO_LCD_FILTER_DEFAULT
)
222 options
->lcd_filter
= other
->lcd_filter
;
223 if (other
->hint_style
!= CAIRO_HINT_STYLE_DEFAULT
)
224 options
->hint_style
= other
->hint_style
;
225 if (other
->hint_metrics
!= CAIRO_HINT_METRICS_DEFAULT
)
226 options
->hint_metrics
= other
->hint_metrics
;
227 if (other
->round_glyph_positions
!= CAIRO_ROUND_GLYPH_POS_DEFAULT
)
228 options
->round_glyph_positions
= other
->round_glyph_positions
;
230 slim_hidden_def (cairo_font_options_merge
);
233 * cairo_font_options_equal:
234 * @options: a #cairo_font_options_t
235 * @other: another #cairo_font_options_t
237 * Compares two font options objects for equality.
239 * Return value: %TRUE if all fields of the two font options objects match.
240 * Note that this function will return %FALSE if either object is in
246 cairo_font_options_equal (const cairo_font_options_t
*options
,
247 const cairo_font_options_t
*other
)
249 if (cairo_font_options_status ((cairo_font_options_t
*) options
))
251 if (cairo_font_options_status ((cairo_font_options_t
*) other
))
254 if (options
== other
)
257 return (options
->antialias
== other
->antialias
&&
258 options
->subpixel_order
== other
->subpixel_order
&&
259 options
->lcd_filter
== other
->lcd_filter
&&
260 options
->hint_style
== other
->hint_style
&&
261 options
->hint_metrics
== other
->hint_metrics
&&
262 options
->round_glyph_positions
== other
->round_glyph_positions
);
264 slim_hidden_def (cairo_font_options_equal
);
267 * cairo_font_options_hash:
268 * @options: a #cairo_font_options_t
270 * Compute a hash for the font options object; this value will
271 * be useful when storing an object containing a #cairo_font_options_t
274 * Return value: the hash value for the font options object.
275 * The return value can be cast to a 32-bit type if a
276 * 32-bit hash value is needed.
281 cairo_font_options_hash (const cairo_font_options_t
*options
)
283 if (cairo_font_options_status ((cairo_font_options_t
*) options
))
284 options
= &_cairo_font_options_nil
; /* force default values */
286 return ((options
->antialias
) |
287 (options
->subpixel_order
<< 4) |
288 (options
->lcd_filter
<< 8) |
289 (options
->hint_style
<< 12) |
290 (options
->hint_metrics
<< 16));
292 slim_hidden_def (cairo_font_options_hash
);
295 * cairo_font_options_set_antialias:
296 * @options: a #cairo_font_options_t
297 * @antialias: the new antialiasing mode
299 * Sets the antialiasing mode for the font options object. This
300 * specifies the type of antialiasing to do when rendering text.
305 cairo_font_options_set_antialias (cairo_font_options_t
*options
,
306 cairo_antialias_t antialias
)
308 if (cairo_font_options_status (options
))
311 options
->antialias
= antialias
;
313 slim_hidden_def (cairo_font_options_set_antialias
);
316 * cairo_font_options_get_antialias:
317 * @options: a #cairo_font_options_t
319 * Gets the antialiasing mode for the font options object.
321 * Return value: the antialiasing mode
326 cairo_font_options_get_antialias (const cairo_font_options_t
*options
)
328 if (cairo_font_options_status ((cairo_font_options_t
*) options
))
329 return CAIRO_ANTIALIAS_DEFAULT
;
331 return options
->antialias
;
335 * cairo_font_options_set_subpixel_order:
336 * @options: a #cairo_font_options_t
337 * @subpixel_order: the new subpixel order
339 * Sets the subpixel order for the font options object. The subpixel
340 * order specifies the order of color elements within each pixel on
341 * the display device when rendering with an antialiasing mode of
342 * %CAIRO_ANTIALIAS_SUBPIXEL. See the documentation for
343 * #cairo_subpixel_order_t for full details.
348 cairo_font_options_set_subpixel_order (cairo_font_options_t
*options
,
349 cairo_subpixel_order_t subpixel_order
)
351 if (cairo_font_options_status (options
))
354 options
->subpixel_order
= subpixel_order
;
356 slim_hidden_def (cairo_font_options_set_subpixel_order
);
359 * cairo_font_options_get_subpixel_order:
360 * @options: a #cairo_font_options_t
362 * Gets the subpixel order for the font options object.
363 * See the documentation for #cairo_subpixel_order_t for full details.
365 * Return value: the subpixel order for the font options object
369 cairo_subpixel_order_t
370 cairo_font_options_get_subpixel_order (const cairo_font_options_t
*options
)
372 if (cairo_font_options_status ((cairo_font_options_t
*) options
))
373 return CAIRO_SUBPIXEL_ORDER_DEFAULT
;
375 return options
->subpixel_order
;
379 * _cairo_font_options_set_lcd_filter:
380 * @options: a #cairo_font_options_t
381 * @lcd_filter: the new LCD filter
383 * Sets the LCD filter for the font options object. The LCD filter
384 * specifies how pixels are filtered when rendered with an antialiasing
385 * mode of %CAIRO_ANTIALIAS_SUBPIXEL. See the documentation for
386 * #cairo_lcd_filter_t for full details.
389 _cairo_font_options_set_lcd_filter (cairo_font_options_t
*options
,
390 cairo_lcd_filter_t lcd_filter
)
392 if (cairo_font_options_status (options
))
395 options
->lcd_filter
= lcd_filter
;
399 * _cairo_font_options_get_lcd_filter:
400 * @options: a #cairo_font_options_t
402 * Gets the LCD filter for the font options object.
403 * See the documentation for #cairo_lcd_filter_t for full details.
405 * Return value: the LCD filter for the font options object
408 _cairo_font_options_get_lcd_filter (const cairo_font_options_t
*options
)
410 if (cairo_font_options_status ((cairo_font_options_t
*) options
))
411 return CAIRO_LCD_FILTER_DEFAULT
;
413 return options
->lcd_filter
;
417 * _cairo_font_options_set_round_glyph_positions:
418 * @options: a #cairo_font_options_t
419 * @round: the new rounding value
421 * Sets the rounding options for the font options object. If rounding is set, a
422 * glyph's position will be rounded to integer values.
425 _cairo_font_options_set_round_glyph_positions (cairo_font_options_t
*options
,
426 cairo_round_glyph_positions_t round
)
428 if (cairo_font_options_status (options
))
431 options
->round_glyph_positions
= round
;
435 * _cairo_font_options_get_round_glyph_positions:
436 * @options: a #cairo_font_options_t
438 * Gets the glyph position rounding option for the font options object.
440 * Return value: The round glyph posistions flag for the font options object.
442 cairo_round_glyph_positions_t
443 _cairo_font_options_get_round_glyph_positions (const cairo_font_options_t
*options
)
445 if (cairo_font_options_status ((cairo_font_options_t
*) options
))
446 return CAIRO_ROUND_GLYPH_POS_DEFAULT
;
448 return options
->round_glyph_positions
;
452 * cairo_font_options_set_hint_style:
453 * @options: a #cairo_font_options_t
454 * @hint_style: the new hint style
456 * Sets the hint style for font outlines for the font options object.
457 * This controls whether to fit font outlines to the pixel grid,
458 * and if so, whether to optimize for fidelity or contrast.
459 * See the documentation for #cairo_hint_style_t for full details.
464 cairo_font_options_set_hint_style (cairo_font_options_t
*options
,
465 cairo_hint_style_t hint_style
)
467 if (cairo_font_options_status (options
))
470 options
->hint_style
= hint_style
;
472 slim_hidden_def (cairo_font_options_set_hint_style
);
475 * cairo_font_options_get_hint_style:
476 * @options: a #cairo_font_options_t
478 * Gets the hint style for font outlines for the font options object.
479 * See the documentation for #cairo_hint_style_t for full details.
481 * Return value: the hint style for the font options object
486 cairo_font_options_get_hint_style (const cairo_font_options_t
*options
)
488 if (cairo_font_options_status ((cairo_font_options_t
*) options
))
489 return CAIRO_HINT_STYLE_DEFAULT
;
491 return options
->hint_style
;
495 * cairo_font_options_set_hint_metrics:
496 * @options: a #cairo_font_options_t
497 * @hint_metrics: the new metrics hinting mode
499 * Sets the metrics hinting mode for the font options object. This
500 * controls whether metrics are quantized to integer values in
502 * See the documentation for #cairo_hint_metrics_t for full details.
507 cairo_font_options_set_hint_metrics (cairo_font_options_t
*options
,
508 cairo_hint_metrics_t hint_metrics
)
510 if (cairo_font_options_status (options
))
513 options
->hint_metrics
= hint_metrics
;
515 slim_hidden_def (cairo_font_options_set_hint_metrics
);
518 * cairo_font_options_get_hint_metrics:
519 * @options: a #cairo_font_options_t
521 * Gets the metrics hinting mode for the font options object.
522 * See the documentation for #cairo_hint_metrics_t for full details.
524 * Return value: the metrics hinting mode for the font options object
529 cairo_font_options_get_hint_metrics (const cairo_font_options_t
*options
)
531 if (cairo_font_options_status ((cairo_font_options_t
*) options
))
532 return CAIRO_HINT_METRICS_DEFAULT
;
534 return options
->hint_metrics
;