windows-server-2003/printscan/print/drivers/usermode/lib/ufl/api/ufl.h

/*
 *    Adobe Universal Font Libary
 *
 *    Copyright (c) 1996 Adobe Systems Inc.
 *    All Rights Reserved
 *
 *    UFL -- UFL APIs.
 *
 *
 *
 * $Header:
 */

#ifndef _H_UFL
#define _H_UFL

/*=============================================================================*
 * Include files used by this interface                                        *
 *=============================================================================*/
#include "UFLTypes.h"
#include "UFLClien.h"

/*=============================================================================*

                            Theory of Operation

Universal Font Library allows its client to download a font incrementally or a
font subset. It has the following functionalities.

1. Depending on the downloading type, UFL requests its client to download a
   procset in order for it to create a font.

2. The type of font downloading that UFL currently supports are:

Font Type      Method       DownLoad Type                Comment
=============================================================================
TrueType       Subset       Unhinted Outline Font T1.
TrueType       Subset       Hinted Bitmap Font T3.
TrueType       Subset       Type 42                      Only works on 2013+.
TrueType       Subset       CID
TrueTypeOpen   Subset       Type 1                       Use XCF
TrueTypeOpen   Subset       Type 2                       Use XCF
TrueTypeOpen   Subset       CID                          Use XCF

3. UFL only supports glyph index string.

4. For CFF font, it determines SEAC characters and downloads required
   characters.

5. It keeps track of glyphs that have been downloaded in a font.

6. Provides VM usage of a downloaded font to the client.

7. UFL does not know how to rendering a font.  If the client wishes to download
   a TT font as a T1 or T3 font, then the client needs to provide callback
   functions that UFL uses to get the outline or bitmap of a character.


The following functions are not part of UFL.

1. Memory management: UFL does not check for VM, allocates VM usage, or takes
   care of save/restore level.  Instead, a client can request the amount of VM
   needed for an incremental download request. UFL also returns the amount of
   VM usage for the request.

2. Font managements: UFL does not keep track of the fonts that have been
   downloaded. Its client keeps this information so DSC %%IncludeFont and
   %%DocumentNeededFont should be generated by the client.

3. UFL does not do anything else with the base font that it has created: it
   does not flip to match the platform's x and y directions, it does not apply
   synthetic emboldening or obliquing, and it does not scale the font.


In order to use the UFL, the following sequences need to be performed.

1. Initialize the library by calling UFLInit().

2. Create a Universal Font Object (UFO) by calling UFLNewFont(). The UFO is an
   opaque object that does the real work in a font downloading process.

3. Download a base font (a font with only .notdef character) or a font subset
   by calling UFLDownloadIncr().

4. To add more CharStrings into an already downloaded font, a client would call
   the same UFLDownloadIncr().

5. Once a font is no longer needed, delete the font in the printer by calling
   UFLUndefineFont() and delete its UFO object by calling UFLDeleteFont().

6. Terminate the library by calling UFLCleanUp()

===============================================================================*/


/*=============================================================================*
 * Constants                                                                   *
 *=============================================================================*/

/* this string is shared among all T1/T3/T42 downloading */
extern const char *gnotdefArray;
extern const char *Notdef;
extern const char *Hyphen;
extern const char *Minus;
extern const char *SftHyphen;
extern const char *UFLSpace;
extern const char *Bullet;
extern const char *nilStr;


/*=============================================================================*
 * Scalar Types                                                                *
 *=============================================================================*/

#ifdef __cplusplus
extern "C" {
#endif


/*
 * The Metrowerks 68k Mac compiler expects functions to return pointers in A0
 * instead of D0. This pragma tells it they are in D0.
 */
#if defined(MAC_ENV) && defined(__MWERKS__) && !defined(powerc)
#pragma pointers_in_D0
#endif


/*
 * If the fontIndex in UFLFontDataInfo is set to Unknown, UFL will try to find
 * it in TTC In the later case, client shoudl provide either UniqueNameA or
 * UniqueNameW.
 */
#define  FONTINDEX_UNKNOWN      0xFFFF

typedef struct _t_UFLXUID {
    unsigned long    sSize;     /* Number of longs in the XUID array */
    unsigned long    *pXUID;
} UFLXUID;


/*
 * FontData info. If the font is a TT font and we want to access some data
 * from the TT file, we use this structure - it is common for T1/T3/T42 - it's
 * part of info provided in the UFLRequest structure by client.
 */
typedef struct _t_UFLFontDataInfo {
    unsigned long       maxGlyphs;         /* # of glyphs in this PS font to create */

    /* This may be initialized by UFL even though the client may provide it. */
    unsigned long       cNumGlyphs;        /* # of glyphs in this TT font file: we may use only part of them. */

    /* stuff to handle TTC - provided by client */
    char                *pUniqueNameA;     /* an ANSI string to uniquely identify this font in a TTC */
    unsigned short      *pUniqueNameW;     /* a Unicode string to uniquely identify this font */

    /* stuff to handle TTC - UFL may initialize this using UniqueName provided by client. */
    unsigned long       offsetToTableDir ; /* offset to the TableDirectory - non-zero in TTC files */

    UFLXUID             xuid;              /* number of longs in the XUID array and the XUID array */
    unsigned short      fontIndex ;        /* font index in a TTC file */
    char                reserved[2];       /* make this structure's size as multiple of DWORD */
} UFLFontDataInfo;


typedef struct tagUFLCMapInfo {
    char        CMapName[32];    /* Our names are limited to 30 chars. */
    short int   CMapVersion;     /* This is an integer. See CMAP doc. */
    short int   CMapType;

    char        Registry[20];    /* Ours are limited to 20 chars. */
    char        Ordering[20];    /* Ours are limited to 20 chars. */
    short int   Supplement;

    char        reserved[2];     /* make this structure's size as multiple of DWORD */
} UFLCMapInfo;


/*
 * UFL TT Font infos. If the font is a TT font downloaded as Type 42, then this
 * structure needs to be provided in the UFLRequest structure.
 */
typedef struct _t_UFLTTFontInfo {
    UFLFontDataInfo     fData;
    unsigned short int  bUseIdentityCMap;   /* If this is non-zero, CMap, CIDCount, BUpdateCIDMap are ignored. */
    UFLCMapInfo         CMap;               /* used only if bUseIdentityCMap is 0. */
    unsigned short int  CIDCount;           /* (max) number of glyphs */
    unsigned short int  bUpdateCIDMap;      /* initialize/update CIDMap when non-zero */
    char                CIDFontName[256];   /* used when the font is a FE CID font */
    char                reserved[2];        /* make this structure's size as multiple of DWORD */
} UFLTTFontInfo;


/*
 * UFLTTT1FontInfo structure. If the font is a TT font downloaded as type 1,
 * then this structure needs to  be provided in the UFLRequest structure.
 */
typedef struct _t_UFLTTT1FontInfo {
    UFLFontDataInfo     fData;
    UFLBool             bEExec;           /* To be used when download a TT as a type 1 font. */
    UFLFixedMatrix      matrix;           /* font matrix that the TT font is rendering */
    long                lNumNT4SymGlyphs; /* NT4 use only: number of symbol glyphs */
} UFLTTT1FontInfo;


/*
 * UFLTTT3FontInfo structure. If the font is a TT font downloaded as type 3,
 * then this structure needs to  be provided in the UFLRequest structure.
 */
typedef struct _t_UFLTTT3FontInfo {
    UFLFontDataInfo     fData;
    unsigned long       cbMaxGlyphs;      /* Size of the largest glyphs */
    UFLFixedMatrix      matrix;           /* Font matrix that the TT font is rendering. */
    UFLFixed            bbox[4];
    long                lNumNT4SymGlyphs; /* NT4 use only: number of symbol glyphs */
} UFLTTT3FontInfo;


/*===============================================================================*
 * UFL CFF Infos                                                                 *
 *===============================================================================*/

/* uniqueIDMethod options */
enum {
    kKeepUID,       /* Define UID with the one in the font. */
    kUndefineUID,   /* Don't define UID in the font */
    kUserID         /* Replace UID with the one in StreamerOpts */
};


/* Subroutine flattening options:  */
enum {
    kKeepSubrs,     /* Keep all subroutines intact */
    kFlattenSubrs   /* Flatten/unwind all the subroutines */
};

typedef struct _t_UFLCFFReadBuf {
    unsigned long cbBuf;
    unsigned char *pBuf;
} UFLCFFReadBuf;

typedef struct _t_UFLCFFFontInfo {
    unsigned long       uniqueID;
    UFLFontDataInfo     fData;                  /* need to use some of the data here intelligently */

    unsigned long       fontLength;             /* Size of 'CFF ' table */
    void PTR_PREFIX     **ppFontData;           /* pointer to 'CFF ' table pointer. Nil if read from the file. */

    unsigned short int  maxBlockSize;           /* max data size that client's stream output function can handle
                                                   at a time. XCF requires this info optionally. */

    unsigned short int  uniqueIDMethod:2,       /* UniqueID method */
                        subrFlatten:1,          /* Flatten subrs */
                        usePSName:1,            /* Use correct PostScript Name for the downloaded characters */
                        useSpecialEncoding:1,   /* Use special encoding */
                        escDownloadFace:1,      /* set when requested thru Esc(DOWNLOADFACE) */
                        type1:1;                /* set when the font is a Type 1 font. */

    char                baseName[256];          /* used to create a PS name with prefix */

    UFLCFFReadBuf       readBuf;                /* 'CFF ' table read buffer object: used if ppFontData is nil. */
} UFLCFFFontInfo;


/*
 * Extra information for support of vertical proportional font
 * Fix #287084, #309104, and #309482
 */
typedef struct _t_UFLVPFInfo {
    int             nPlatformID;                /* 0:9x 1:NT4 2:W2K                 */
    int             nSkewElement;               /* 2:9x 3:NT4/W2K                   */
    char*           pszTangentTheta;            /* tan(18deg):9x/NT4 tan(20deg):W2K */
} UFLVPFInfo;




typedef struct _t_UFLRequest {
    UFLDownloadType lDownloadFormat;            /* Client request download method.  */

    UFLHANDLE       hFontInfo;                  /* Special info based on Download font format. For example,
                                                   if the downloaded font is a true type font then this would
                                                   point to a UFLTTFontInfo data structure. */

    char            *pszFontName;               /* font name */

    UFLHANDLE       hData;                      /* Client's private data. When UFL calls the client's callback
                                                   routine, it returns this handle to the client. */

    short           subfontNumber;              /* subfont number of this font */

    long            useMyGlyphName;             /* If 1, use the glyph names passed in by client */
    char            *pszEncodeName;             /* Font encoding. If this field is NULL, then creat a font
                                                   with names UFL likes. */
    unsigned char   *pEncodeNameList;           /* Fix bug #274008 */
    unsigned short  *pwCommonEncode;
    unsigned short  *pwExtendEncode;
    unsigned char   *pMacGlyphNameList;         /* mac Glyph Names */

    UFLVPFInfo      vpfinfo;                    /* Fix bug #287084, #309104, and #309482 */
    UFLHANDLE       hHostFontData;              /* %hostfont% support */

    UFLBool         bPatchQXPCFFCID;            /* Fix bug #341904 */
} UFLRequest;



/*
 * A structure to pass information between Client and UFL for incremental
 * downloading.
 */
typedef struct _t_UFLGlyphsInfo {
    short int       sCount;           /* number of Glyphs in pGlyphIndices */
    UFLGlyphID      *pGlyphIndices;   /* list of Glyphs IDs */
    unsigned short  *pCharIndex;      /* corresponding Character-codes/indices in this font */
    unsigned char   **ppGlyphNames;   /* corresponding Glyphs Names */
    unsigned short  *pCode;           /* corresponding Unicode or Script-Code points */
    char            reserved[2];      /* make this structure's size as multiple of DWORD */
}UFLGlyphsInfo;


/*
 * Prefix and the font instance name generator macros using it. These prefix
 * are used when downloading an OpenType font (cheifly to tell Distiller its
 * real font name).
 */
#define CFFPREFIX   "ADBCFF+"

/* Fix for #507985: need to use different prefixes for H and V (9x only) */
#define CFFPREFIX_H "ADBCFA+"
#define CFFPREFIX_V "ADBCFB+"


#define CREATE_ADCFXX_FONTNAME(fmtfn, dest, cchDest, num, basename) \
    (fmtfn)((dest), (cchDest), "ADCF%c%c+%s", \
                        (char)((((num)&0x00F0)>>4)+'A'), \
                        (char)((((num)&0x000F)   )+'A'), \
                        (basename))

#define CREATE_ADXXXX_FONTNAME(fmtfn, dest, cchDest, num, basename) \
    (fmtfn)((dest), (cchDest), "AD%c%c%c%c+%s", \
                        (char)((((num)&0xF000)>>12)+'A'), \
                        (char)((((num)&0x0F00)>> 8)+'A'), \
                        (char)((((num)&0x00F0)>> 4)+'A'), \
                        (char)((((num)&0x000F)    )+'A'), \
                        (basename))


/*
 * %hostfont% support
 */
typedef enum
{
    HOSTFONT_UFLREQUEST_GET_NAME,
    HOSTFONT_UFLREQUEST_IS_ALLOWED,
    HOSTFONT_UFLREQUEST_SET_CURRENTNAME,
} HOSTFONT_UFLREQUEST;

/*
 * Special definition to work around %hostfont% RIP bug #388111
 * Change the value to 0 when the bug is fixed.
 */
#define HOSTFONT_REQUIRE_VMTX 1


/*=============================================================================
                                UFLInit

    Initialize UFL library. Typically, a client would call UFLInit at the
    beginning of a session.  It calls UFLTerminate to end a session.

    bDLGlyphTracking (in) -- TRUE if UFL keeps track of downloaded glyphs
    pMemObj (in)          -- points to UFLMemObj structure. UFL uses this
                             object to allocate and free memory.
    pFontProcs (in)       -- points to the data structure that contains the
                             font related callback functions.
    pStdProcs (in)        -- points to the data structure that contains the
                             standard library callback functions.
                             THIS IS CURRENTLY NOT USED.
    pOutDev (in)          -- points to printer specific data.

    If the function succeeds, it returns a handle to the client. If it fails,
    it returns nil.
===============================================================================*/

UFLHANDLE
UFLInit(
    const UFLBool           bDLGlyphTracking,
    const UFLMemObj         *pMemObj,
    const UFLFontProcs      *pFontProcs,
    const UFLOutputDevice   *pOutDev
    );


/*=============================================================================
                            UFLCleanUp

    Terminate a UFL session.

    handle (in) -- UFL handle that is obtained when UFLInit is called.

===============================================================================*/

void
UFLCleanUp(
    UFLHANDLE handle
    );


/*=============================================================================
                            UFLNewFont

    Initialize a font and validate a UFL request. This function needs to be
    called before a client makes a call to any other font handling APIs.
    If the request is valid, the function sets up the font global data structure.

    session (in)  -- UFL handle that is obtained when UFLInit is called.
    pRequest (in) -- points to the UFLRequest data structure.

    returns -- Handle to data stored for this font, or nil if unsuccessful

===============================================================================*/

UFO
UFLNewFont(
    const UFLHANDLE     session,
    const UFLRequest*   pRequest
    );


/*=============================================================================
                            UFLTestRestricted

===============================================================================*/

UFLBool
bUFLTestRestricted(
    const UFLHANDLE     h,
    const UFLRequest    *pRequest
    );


/*=============================================================================
                            UFLVMNeeded

    Get a guestimate of VM needed for a download request.

    aFont (in)      -- UFL handle that is obtained when UFLBeginFont is called.
    pGlyphs (in)    -- pointer to a UFLGlyphsInfo - has all the information
                       about this updating, including:
                       Number of glyphs to be output
                       List of output glyphs, each glyph is 2 bytes long
                       List of glyph names.  This list can be NULL. If this is
                       the case, UFL uses the name defined in the font
                       A list of indices to be used to index the ppGlyphNames list.
                       A List of Unicode or Script-code points
                       ... and ... depends on the extension to UFLGlyphsInfo
                       structure ....
    pVMNeeded (out) -- Amount of VM needed.
    pFCNeeded (out) -- Amount of FC needed.

    returns:
    noErr or error code if unsuccessful

===============================================================================*/

UFLErrCode
UFLVMNeeded(
    const UFO           aFont,
    const UFLGlyphsInfo *pGlyphs,
    unsigned long       *pVMNeeded,
    unsigned long       *pFCNeeded
    );



/*=============================================================================
                            UFLDownloadIncr

    Downloads a font incrementally. The first time this is called for a
    particular font, it will create a base font, and download a set of
    requested characters. Subsequent calls on the same font will download
    additional characters.

    aFont (in)     -- UFL handle that is obtained when UFLBeginFont is called.
    pGlyphs (in)   -- pointer to a UFLGlyphsInfo - has all the information
                      about this updating, including:
                      Number of glyphs to be output
                      List of output glyphs, each glyph is 2 bytes long
                      List of glyph names.  This list can be NULL. If this is
                      the case, UFL uses the name defined in the font
                      A list of indices to be used to index the ppGlyphNames list.
                      A List of Unicode or Script-code points
                      ... and ... depends on the extension to UFLGlyphsInfo
                      structure ....
    pVMUsage (out) -- pointer to the amount of VM used by this request.

    returns:
    noErr or error code if unsuccessful

===============================================================================*/

UFLErrCode
UFLDownloadIncr(
    const UFO           aFont,
    const UFLGlyphsInfo *pGlyphs,
    unsigned long       *pVMUsage,
    unsigned long       *pFCUsage
    );


/*=============================================================================
                            UFLDeleteFont

    Delete UFL internal data. UFL does not output any PostScript to delete
    the font on the printer since this has to do with how its client manages
    printer resources.

    aFont (in) -- UFL handle that is obtained when UFLBeginFont is called.

===============================================================================*/

void
UFLDeleteFont(
    UFO aFont
    );


/*===========================================================================
                            UFLUndefineFont

    Undefine a font on the printer.

    aFont (in) -- UFL handle that is obtained when UFLBeginFont is called.

    returns:
    noErr or error code if unsuccessful

==============================================================================*/

UFLErrCode
UFLUndefineFont(
    const UFO aFont
    );


/*=============================================================================
                            UFLCopyFont

    Copy a font on the printer - with new Encoding vector

    aFont (in) -- UFL handle to a UFObj created earlier
    request    -- has pszFontName, new hData, and new Encoding for this copy.

    returns:
    Handle to data stored for this font, or nil if unsuccessful.

===============================================================================*/

UFO
UFLCopyFont(
    const UFO   h,
    const UFLRequest* pRequest
    );


/*=============================================================================
                            UFLGIDsToCIDs

    This function can only be used with a CID CFF font. It is used to obtain
    CIDs from a list of GIDs.

    aFont (in)   -- UFL handle that is obtained when UFLBeginFont is called.
    cGlyphs (in) -- Number of glyhs (GIDs) to be converted.
    pGIDs  (in)  -- GID list.
    pCIDs  (out) -- Result CIDs.

    returns:
    noErr or error code if unsuccessful

===============================================================================*/

UFLErrCode
UFLGIDsToCIDs(
    const UFO        aFont,
    const short      cGlyphs,
    const UFLGlyphID *pGIDs,
    unsigned short   *pCIDs
    );


/* undo the Metrowerks pragma. */
#if defined(MAC_ENV) && defined(__MWERKS__) && !defined(powerc)
#pragma pointers_in_A0
#endif

#ifdef __cplusplus
}
#endif

#endif