michael@0: 
michael@0: /*
michael@0:  * Copyright 2006 The Android Open Source Project
michael@0:  *
michael@0:  * Use of this source code is governed by a BSD-style license that can be
michael@0:  * found in the LICENSE file.
michael@0:  */
michael@0: 
michael@0: 
michael@0: #ifndef SkFontHost_DEFINED
michael@0: #define SkFontHost_DEFINED
michael@0: 
michael@0: #include "SkTypeface.h"
michael@0: 
michael@0: class SkDescriptor;
michael@0: class SkScalerContext;
michael@0: struct SkScalerContextRec;
michael@0: class SkStream;
michael@0: class SkWStream;
michael@0: 
michael@0: /** \class SkFontHost
michael@0: 
michael@0:     This class is ported to each environment. It is responsible for bridging
michael@0:     the gap between the (sort of) abstract class SkTypeface and the
michael@0:     platform-specific implementation that provides access to font files.
michael@0: 
michael@0:     One basic task is for each create (subclass of) SkTypeface, the FontHost is
michael@0:     responsible for assigning a uniqueID. The ID should be unique for the
michael@0:     underlying font file/data, not unique per typeface instance. Thus it is
michael@0:     possible/common to request a typeface for the same font more than once
michael@0:     (e.g. asking for the same font by name several times). The FontHost may
michael@0:     return seperate typeface instances in that case, or it may choose to use a
michael@0:     cache and return the same instance (but calling typeface->ref(), since the
michael@0:     caller is always responsible for calling unref() on each instance that is
michael@0:     returned). Either way, the fontID for those instance(s) will be the same.
michael@0:     In addition, the fontID should never be set to 0. That value is used as a
michael@0:     sentinel to indicate no-font-id.
michael@0: 
michael@0:     The major aspects are:
michael@0:     1) Given either a name/style, return a subclass of SkTypeface that
michael@0:         references the closest matching font available on the host system.
michael@0:     2) Given the data for a font (either in a stream or a file name), return
michael@0:         a typeface that allows access to that data.
michael@0:     3) Each typeface instance carries a 32bit ID for its corresponding font.
michael@0:         SkFontHost turns that ID into a stream to access the font's data.
michael@0:     4) Given a font ID, return a subclass of SkScalerContext, which connects a
michael@0:         font scaler (e.g. freetype or other) to the font's data.
michael@0:     5) Utilites to manage the font cache (budgeting) and gamma correction
michael@0: */
michael@0: class SK_API SkFontHost {
michael@0: public:
michael@0:     /** LCDs either have their color elements arranged horizontally or
michael@0:      vertically. When rendering subpixel glyphs we need to know which way
michael@0:      round they are.
michael@0: 
michael@0:      Note, if you change this after startup, you'll need to flush the glyph
michael@0:      cache because it'll have the wrong type of masks cached.
michael@0: 
michael@0:      @deprecated use SkPixelGeometry instead.
michael@0:      */
michael@0:     enum LCDOrientation {
michael@0:         kHorizontal_LCDOrientation = 0,    //!< this is the default
michael@0:         kVertical_LCDOrientation   = 1
michael@0:     };
michael@0: 
michael@0:     /** @deprecated set on Device creation. */
michael@0:     static void SetSubpixelOrientation(LCDOrientation orientation);
michael@0:     /** @deprecated get from Device. */
michael@0:     static LCDOrientation GetSubpixelOrientation();
michael@0: 
michael@0:     /** LCD color elements can vary in order. For subpixel text we need to know
michael@0:      the order which the LCDs uses so that the color fringes are in the
michael@0:      correct place.
michael@0: 
michael@0:      Note, if you change this after startup, you'll need to flush the glyph
michael@0:      cache because it'll have the wrong type of masks cached.
michael@0: 
michael@0:      kNONE_LCDOrder means that the subpixel elements are not spatially
michael@0:      separated in any usable fashion.
michael@0: 
michael@0:      @deprecated use SkPixelGeometry instead.
michael@0:      */
michael@0:     enum LCDOrder {
michael@0:         kRGB_LCDOrder = 0,    //!< this is the default
michael@0:         kBGR_LCDOrder = 1,
michael@0:         kNONE_LCDOrder = 2
michael@0:     };
michael@0: 
michael@0:     /** @deprecated set on Device creation. */
michael@0:     static void SetSubpixelOrder(LCDOrder order);
michael@0:     /** @deprecated get from Device. */
michael@0:     static LCDOrder GetSubpixelOrder();
michael@0: 
michael@0: private:
michael@0:     /** Return a new, closest matching typeface given either an existing family
michael@0:         (specified by a typeface in that family) or by a familyName and a
michael@0:         requested style.
michael@0:         1) If familyFace is null, use familyName.
michael@0:         2) If familyName is null, use data (UTF-16 to cover).
michael@0:         3) If all are null, return the default font that best matches style
michael@0:      */
michael@0:     static SkTypeface* CreateTypeface(const SkTypeface* familyFace,
michael@0:                                       const char familyName[],
michael@0:                                       SkTypeface::Style style);
michael@0: 
michael@0:     /** Return a new typeface given the data buffer. If the data does not
michael@0:         represent a valid font, returns null.
michael@0: 
michael@0:         If a typeface instance is returned, the caller is responsible for
michael@0:         calling unref() on the typeface when they are finished with it.
michael@0: 
michael@0:         The returned typeface may or may not have called ref() on the stream
michael@0:         parameter. If the typeface has not called ref(), then it may have made
michael@0:         a copy of the releveant data. In either case, the caller is still
michael@0:         responsible for its refcnt ownership of the stream.
michael@0:      */
michael@0:     static SkTypeface* CreateTypefaceFromStream(SkStream*);
michael@0: 
michael@0:     /** Return a new typeface from the specified file path. If the file does not
michael@0:         represent a valid font, this returns null. If a typeface is returned,
michael@0:         the caller is responsible for calling unref() when it is no longer used.
michael@0:      */
michael@0:     static SkTypeface* CreateTypefaceFromFile(const char path[]);
michael@0: 
michael@0:     ///////////////////////////////////////////////////////////////////////////
michael@0: 
michael@0:     friend class SkScalerContext;
michael@0:     friend class SkTypeface;
michael@0: };
michael@0: 
michael@0: #endif