freetype2/freetype/ftgzip.h

0001 /****************************************************************************
0002  *
0003  * ftgzip.h
0004  *
0005  *   Gzip-compressed stream support.
0006  *
0007  * Copyright (C) 2002-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 #ifndef FTGZIP_H_
0020 #define FTGZIP_H_
0021
0022 #include <freetype/freetype.h>
0023
0024 #ifdef FREETYPE_H
0025 #error "freetype.h of FreeType 1 has been loaded!"
0026 #error "Please fix the directory search order for header files"
0027 #error "so that freetype.h of FreeType 2 is found first."
0028 #endif
0029
0030
0031 FT_BEGIN_HEADER
0032
0033   /**************************************************************************
0034    *
0035    * @section:
0036    *   gzip
0037    *
0038    * @title:
0039    *   GZIP Streams
0040    *
0041    * @abstract:
0042    *   Using gzip-compressed font files.
0043    *
0044    * @description:
0045    *   In certain builds of the library, gzip compression recognition is
0046    *   automatically handled when calling @FT_New_Face or @FT_Open_Face.
0047    *   This means that if no font driver is capable of handling the raw
0048    *   compressed file, the library will try to open a gzipped stream from it
0049    *   and re-open the face with it.
0050    *
0051    *   The stream implementation is very basic and resets the decompression
0052    *   process each time seeking backwards is needed within the stream,
0053    *   which significantly undermines the performance.
0054    *
0055    *   This section contains the declaration of Gzip-specific functions.
0056    *
0057    */
0058
0059
0060   /**************************************************************************
0061    *
0062    * @function:
0063    *   FT_Stream_OpenGzip
0064    *
0065    * @description:
0066    *   Open a new stream to parse gzip-compressed font files.  This is mainly
0067    *   used to support the compressed `*.pcf.gz` fonts that come with
0068    *   XFree86.
0069    *
0070    * @input:
0071    *   stream ::
0072    *     The target embedding stream.
0073    *
0074    *   source ::
0075    *     The source stream.
0076    *
0077    * @return:
0078    *   FreeType error code.  0~means success.
0079    *
0080    * @note:
0081    *   The source stream must be opened _before_ calling this function.
0082    *
0083    *   Calling the internal function `FT_Stream_Close` on the new stream will
0084    *   **not** call `FT_Stream_Close` on the source stream.  None of the
0085    *   stream objects will be released to the heap.
0086    *
0087    *   This function may return `FT_Err_Unimplemented_Feature` if your build
0088    *   of FreeType was not compiled with zlib support.
0089    */
0090   FT_EXPORT( FT_Error )
0091   FT_Stream_OpenGzip( FT_Stream  stream,
0092                       FT_Stream  source );
0093
0094
0095   /**************************************************************************
0096    *
0097    * @function:
0098    *   FT_Gzip_Uncompress
0099    *
0100    * @description:
0101    *   Decompress a zipped input buffer into an output buffer.  This function
0102    *   is modeled after zlib's `uncompress` function.
0103    *
0104    * @input:
0105    *   memory ::
0106    *     A FreeType memory handle.
0107    *
0108    *   input ::
0109    *     The input buffer.
0110    *
0111    *   input_len ::
0112    *     The length of the input buffer.
0113    *
0114    * @output:
0115    *   output ::
0116    *     The output buffer.
0117    *
0118    * @inout:
0119    *   output_len ::
0120    *     Before calling the function, this is the total size of the output
0121    *     buffer, which must be large enough to hold the entire uncompressed
0122    *     data (so the size of the uncompressed data must be known in
0123    *     advance).  After calling the function, `output_len` is the size of
0124    *     the used data in `output`.
0125    *
0126    * @return:
0127    *   FreeType error code.  0~means success.
0128    *
0129    * @note:
0130    *   This function may return `FT_Err_Unimplemented_Feature` if your build
0131    *   of FreeType was not compiled with zlib support.
0132    *
0133    * @since:
0134    *   2.5.1
0135    */
0136   FT_EXPORT( FT_Error )
0137   FT_Gzip_Uncompress( FT_Memory       memory,
0138                       FT_Byte*        output,
0139                       FT_ULong*       output_len,
0140                       const FT_Byte*  input,
0141                       FT_ULong        input_len );
0142
0143   /* */
0144
0145
0146 FT_END_HEADER
0147
0148 #endif /* FTGZIP_H_ */
0149
0150
0151 /* END */