DWrite font docs

9 files changed, 137 insertions, 3 deletions

diff --git a/doc/public/cairo-docs.xml b/doc/public/cairo-docs.xml
index 96dabab4f..b5afa1b90 100644
--- a/doc/public/cairo-docs.xml
+++ b/doc/public/cairo-docs.xml
@@ -27,6 +27,7 @@
     <xi:include href="xml/cairo-font-options.xml"/>
     <xi:include href="xml/cairo-ft.xml"/>
     <xi:include href="xml/cairo-win32-fonts.xml"/>
+    <xi:include href="xml/cairo-dwrite-fonts.xml"/>
     <xi:include href="xml/cairo-quartz-fonts.xml"/>
     <xi:include href="xml/cairo-user-fonts.xml"/>
   </chapter>
diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt
index 143f60c9f..2aeecdca1 100644
--- a/doc/public/cairo-sections.txt
+++ b/doc/public/cairo-sections.txt
@@ -27,6 +27,12 @@ cairo_win32_scaled_font_get_device_to_logical
 </SECTION>
 
 <SECTION>
+<FILE>cairo-dwrite-fonts</FILE>
+CAIRO_HAS_DWRITE_FONT
+cairo_dwrite_font_face_create_for_dwrite_fontface
+</SECTION>
+
+<SECTION>
 <FILE>cairo-quartz-fonts</FILE>
 CAIRO_HAS_QUARTZ_FONT
 cairo_quartz_font_face_create_for_cgfont
diff --git a/src/cairo-win32.h b/src/cairo-win32.h
index 4f257d7ed..078a70c7b 100644
--- a/src/cairo-win32.h
+++ b/src/cairo-win32.h
@@ -112,6 +112,7 @@ cairo_win32_scaled_font_get_device_to_logical (cairo_scaled_font_t *scaled_font,
 /*
  * Win32 DirectWrite font support
  */
+
 cairo_public cairo_font_face_t *
 cairo_dwrite_font_face_create_for_dwrite_fontface (void *dwrite_font_face);
 
diff --git a/src/meson.build b/src/meson.build
index 2b37fbc0f..612a3fc47 100644
--- a/src/meson.build
+++ b/src/meson.build
@@ -178,6 +178,7 @@ cairo_feature_sources = {
     'win32/cairo-win32-font.c',
   ],
   'cairo-win32-dwrite-font': [
+    'win32/cairo-dwrite-font-public.c',
     'win32/cairo-dwrite-font.cpp',
   ],
   'cairo-gl': [
diff --git a/src/win32/cairo-dwrite-font-public.c b/src/win32/cairo-dwrite-font-public.c
new file mode 100644
index 000000000..c23cb6029
--- /dev/null
+++ b/src/win32/cairo-dwrite-font-public.c
@@ -0,0 +1,118 @@
+/* -*- Mode: c; tab-width: 8; c-basic-offset: 4; indent-tabs-mode: t; -*- */
+/* Cairo - a vector graphics library with display and print output
+ *
+ * Copyright © 2022 Adrian Johnson
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it either under the terms of the GNU Lesser General Public
+ * License version 2.1 as published by the Free Software Foundation
+ * (the "LGPL") or, at your option, under the terms of the Mozilla
+ * Public License Version 1.1 (the "MPL"). If you do not alter this
+ * notice, a recipient may use your version of this file under either
+ * the MPL or the LGPL.
+ *
+ * You should have received a copy of the LGPL along with this library
+ * in the file COPYING-LGPL-2.1; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ * You should have received a copy of the MPL along with this library
+ * in the file COPYING-MPL-1.1
+ *
+ * The contents of this file are subject to the Mozilla Public License
+ * Version 1.1 (the "License"); you may not use this file except in
+ * compliance with the License. You may obtain a copy of the License at
+ * http://www.mozilla.org/MPL/
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
+ * OF ANY KIND, either express or implied. See the LGPL or the MPL for
+ * the specific language governing rights and limitations.
+ *
+ * The Original Code is the cairo graphics library.
+ *
+ * The Initial Developer of the Original Code is Adrian Johnson
+ *
+ * Contributor(s):
+ *	Adrian Johnson <ajohnson@redneon.com>
+ */
+
+
+/* gtkdoc won't scan .cpp files so we wrap the public API in cairo-dwrite-font.cpp
+ * with this .c wrapper containing the gtkdocs for cairo-dwrite-font.cpp.
+ */
+
+#include "cairo-win32-private.h"
+
+/**
+ * SECTION:cairo-dwrite-fonts
+ * @Title: DWrite Fonts
+ * @Short_Description: Font support for Microsoft DWrite
+ * @See_Also: #cairo_font_face_t
+ *
+ * The Microsoft DWrite font backend is primarily used to render text on
+ * Microsoft Windows systems.
+ **/
+
+/**
+ * CAIRO_HAS_DWRITE_FONT:
+ *
+ * Defined if the Microsoft DWrite font backend is available.
+ * This macro can be used to conditionally compile backend-specific code.
+ *
+ * Since: 1.18
+ **/
+
+/**
+ * cairo_dwrite_font_face_create_for_dwrite_fontface:
+ * @dwrite_font_face: A pointer to an #IDWriteFontFace specifying the
+ * DWrite font to use.
+ *
+ * Creates a new font for the DWrite font backend based on a
+ * DWrite font face. This font can then be used with
+ * cairo_set_font_face() or cairo_scaled_font_create().
+
+ * Here is an example of how this function might be used:
+ * <informalexample><programlisting><![CDATA[
+ * #include <cairo-win32.h>
+ * #include <dwrite.h>
+ *
+ * IDWriteFactory* dWriteFactory = NULL;
+ * HRESULT hr = DWriteCreateFactory(
+ *     DWRITE_FACTORY_TYPE_SHARED,
+ *     __uuidof(IDWriteFactory),
+ *    reinterpret_cast<IUnknown**>(&dWriteFactory));
+ *
+ * IDWriteFontCollection *systemCollection;
+ * hr = dWriteFactory->GetSystemFontCollection(&systemCollection);
+ *
+ * UINT32 idx;
+ * BOOL found;
+ * systemCollection->FindFamilyName(L"Segoe UI Emoji", &idx, &found);
+ *
+ * IDWriteFontFamily *family;
+ * systemCollection->GetFontFamily(idx, &family);
+ *
+ * IDWriteFont *dwritefont;
+ * DWRITE_FONT_WEIGHT weight = DWRITE_FONT_WEIGHT_NORMAL;
+ * DWRITE_FONT_STYLE style = DWRITE_FONT_STYLE_NORMAL;
+ * hr = family->GetFirstMatchingFont(weight, DWRITE_FONT_STRETCH_NORMAL, style, &dwritefont);
+ *
+ * IDWriteFontFace *dwriteface;
+ * hr = dwritefont->CreateFontFace(&dwriteface);
+ *
+ * cairo_font_face_t *face;
+ * face = cairo_dwrite_font_face_create_for_dwrite_fontface(dwriteface);
+ * cairo_set_font_face(cr, face);
+ * cairo_set_font_size(cr, 70);
+ * cairo_move_to(cr, 100, 100);
+ * cairo_show_text(cr, "😃");
+ * ]]></programlisting></informalexample>
+ *
+ * Return value: a newly created #cairo_font_face_t. Free with
+ *  cairo_font_face_destroy() when you are done using it.
+ *
+ * Since: 1.18
+ **/
+cairo_font_face_t*
+cairo_dwrite_font_face_create_for_dwrite_fontface (void *dwrite_font_face)
+{
+    return cairo_dwrite_font_face_create_for_dwrite_fontface_internal (dwrite_font_face);
+}
diff --git a/src/win32/cairo-dwrite-font.cpp b/src/win32/cairo-dwrite-font.cpp
index 9c21eebba..afa859fbd 100644
--- a/src/win32/cairo-dwrite-font.cpp
+++ b/src/win32/cairo-dwrite-font.cpp
@@ -1214,9 +1214,8 @@ _cairo_dwrite_has_color_glyphs(void *scaled_font)
     return ((cairo_dwrite_font_face_t *)dwritesf->base.font_face)->have_color;
 }
 
-// WIN32 Helper Functions
 cairo_font_face_t*
-cairo_dwrite_font_face_create_for_dwrite_fontface(void* dwrite_font_face)
+cairo_dwrite_font_face_create_for_dwrite_fontface_internal(void* dwrite_font_face)
 {
     IDWriteFontFace *dwriteface = static_cast<IDWriteFontFace*>(dwrite_font_face);
     // Must do malloc and not C++ new, since Cairo frees this.
diff --git a/src/win32/cairo-win32-font.c b/src/win32/cairo-win32-font.c
index 4cd0a1203..a3e1bd731 100644
--- a/src/win32/cairo-win32-font.c
+++ b/src/win32/cairo-win32-font.c
@@ -71,12 +71,16 @@
 
 /**
  * SECTION:cairo-win32-fonts
- * @Title: Win32 Fonts
+ * @Title: Win32 GDI Fonts
  * @Short_Description: Font support for Microsoft Windows
  * @See_Also: #cairo_font_face_t
  *
  * The Microsoft Windows font backend is primarily used to render text on
  * Microsoft Windows systems.
+ *
+ * Note: Win32 GDI fonts do not support color fonts. Use DWrite fonts
+ * if color font support is required.
+
  **/
 
 /**
diff --git a/src/win32/cairo-win32-private.h b/src/win32/cairo-win32-private.h
index 486b12811..d457b7805 100644
--- a/src/win32/cairo-win32-private.h
+++ b/src/win32/cairo-win32-private.h
@@ -271,6 +271,9 @@ cairo_int_status_t
 _cairo_dwrite_scaled_font_create_win32_scaled_font (cairo_scaled_font_t *scaled_font,
                                                     cairo_scaled_font_t **new_font);
 
+cairo_font_face_t*
+cairo_dwrite_font_face_create_for_dwrite_fontface_internal(void* dwrite_font_face);
+
 #endif /* CAIRO_HAS_DWRITE_FONT */
 
 CAIRO_END_DECLS
diff --git a/util/cairo-trace/trace.c b/util/cairo-trace/trace.c
index 5fe4935ee..fd9a4a38a 100644
--- a/util/cairo-trace/trace.c
+++ b/util/cairo-trace/trace.c
@@ -1597,6 +1597,7 @@ _status_to_string (cairo_status_t status)
 	f(FREETYPE_ERROR);
 	f(WIN32_GDI_ERROR);
 	f(TAG_ERROR);
+	f(DWRITE_ERROR);
     case CAIRO_STATUS_LAST_STATUS:
 	break;
     }