From 9e5eed280dc71108a1e04f673e27e9b5415b9d22 Mon Sep 17 00:00:00 2001
From: Robert Osfield <robert@openscenegraph.com>
Date: Wed, 28 Sep 2005 13:45:32 +0000
Subject: [PATCH] From Joran Jessurun, comments explaining font search rules

---
 include/osgText/Font | 20 +++++++++++++++++++-
 include/osgText/Text |  3 ++-
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/include/osgText/Font b/include/osgText/Font
index 6e4b509fc..485410e90 100644
--- a/include/osgText/Font
+++ b/include/osgText/Font
@@ -37,7 +37,25 @@ enum KerningType
     KERNING_NONE        //no kerning
 };
 
-/** read a font from specified file.*/
+/** Read a font from specified file. The filename may contain a path.
+  * It will search for the font file in the following places in this order: 
+  * - In the current directory
+  * - All paths defined in OSG_FILE_PATH or OSGFILEPATH environment variable
+  * - Filename with path stripped: In the current directory
+  * - Filename with path stripped: All paths defined in OSG_FILE_PATH or OSGFILEPATH
+  *
+  * Then the file will be searched in OS specific directories in the following order:
+  * - Again in the current directory
+  * - Windows: In C:/winnt/fonts
+  * - Windows: In C:/windows/fonts
+  * - Windows: In the fonts directory of the windows install directory
+  * - Other OS: In /usr/share/fonts/ttf
+  * - Other OS: In /usr/share/fonts/ttf/western
+  * - Other OS: In /usr/share/fonts/ttf/decoratives
+  * 
+  * If the given file could not be found, the path part will be stripped and
+  * the file will be searched again in the OS specific directories.
+  */
 extern OSGTEXT_EXPORT Font* readFontFile(const std::string& filename);
 
 
diff --git a/include/osgText/Text b/include/osgText/Text
index f8313b122..cb02e75a9 100644
--- a/include/osgText/Text
+++ b/include/osgText/Text
@@ -42,7 +42,8 @@ public:
     void setFont(Font* font=0);
 
     /** Set the font, loaded from the specified front file, to use to render the text,
-      * setFont("") sets the use of the default font.*/
+      * setFont("") sets the use of the default font.
+      * See the osgText::readFontFile function for how the font file will be located. */
     void setFont(const std::string& fontfile);
 
     /** Get the font. Return 0 if default is being used.*/