ftcache.h 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415
  1. /***************************************************************************/
  2. /* */
  3. /* ftcache.h */
  4. /* */
  5. /* FreeType Cache subsystem (specification). */
  6. /* */
  7. /* Copyright 1996-2001 by */
  8. /* David Turner, Robert Wilhelm, and Werner Lemberg. */
  9. /* */
  10. /* This file is part of the FreeType project, and may only be used, */
  11. /* modified, and distributed under the terms of the FreeType project */
  12. /* license, LICENSE.TXT. By continuing to use, modify, or distribute */
  13. /* this file you indicate that you have read the license and */
  14. /* understand and accept it fully. */
  15. /* */
  16. /***************************************************************************/
  17. /*************************************************************************/
  18. /*************************************************************************/
  19. /*************************************************************************/
  20. /*************************************************************************/
  21. /*************************************************************************/
  22. /********* *********/
  23. /********* WARNING, THIS IS BETA CODE. *********/
  24. /********* *********/
  25. /*************************************************************************/
  26. /*************************************************************************/
  27. /*************************************************************************/
  28. /*************************************************************************/
  29. /*************************************************************************/
  30. #ifndef __FTCACHE_H__
  31. #define __FTCACHE_H__
  32. #include <ft2build.h>
  33. #include FT_GLYPH_H
  34. FT_BEGIN_HEADER
  35. /*************************************************************************/
  36. /* */
  37. /* <Section> */
  38. /* cache_subsystem */
  39. /* */
  40. /* <Title> */
  41. /* Cache Sub-System */
  42. /* */
  43. /* <Abstract> */
  44. /* How to cache face, size, and glyph data with FreeType 2. */
  45. /* */
  46. /* <Description> */
  47. /* This section describes the FreeType 2 cache sub-system which is */
  48. /* stile in beta. */
  49. /* */
  50. /* <Order> */
  51. /* FTC_Manager */
  52. /* FTC_FaceID */
  53. /* FTC_Face_Requester */
  54. /* */
  55. /* FTC_Manager_New */
  56. /* FTC_Manager_Lookup_Face */
  57. /* FTC_Manager_Lookup_Size */
  58. /* */
  59. /* FTC_Node */
  60. /* FTC_Node_Ref */
  61. /* FTC_Node_Unref */
  62. /* */
  63. /* FTC_Font */
  64. /* FTC_ImageDesc */
  65. /* FTC_ImageCache */
  66. /* FTC_ImageCache_New */
  67. /* FTC_ImageCache_Lookup */
  68. /* */
  69. /* FTC_SBit */
  70. /* FTC_SBitCache */
  71. /* FTC_SBitCache_New */
  72. /* FTC_SBitCache_Lookup */
  73. /* */
  74. /* */
  75. /* FTC_Image_Desc */
  76. /* FTC_Image_Cache */
  77. /* FTC_Image_Cache_Lookup */
  78. /* */
  79. /* FTC_SBit_Cache */
  80. /* FTC_SBit_Cache_Lookup */
  81. /* */
  82. /*************************************************************************/
  83. /*************************************************************************/
  84. /*************************************************************************/
  85. /*************************************************************************/
  86. /***** *****/
  87. /***** BASIC TYPE DEFINITIONS *****/
  88. /***** *****/
  89. /*************************************************************************/
  90. /*************************************************************************/
  91. /*************************************************************************/
  92. /*************************************************************************/
  93. /* */
  94. /* <Type> */
  95. /* FTC_FaceID */
  96. /* */
  97. /* <Description> */
  98. /* A generic pointer type that is used to identity face objects. The */
  99. /* contents of such objects is application-dependent. */
  100. /* */
  101. typedef FT_Pointer FTC_FaceID;
  102. /*************************************************************************/
  103. /* */
  104. /* <FuncType> */
  105. /* FTC_Face_Requester */
  106. /* */
  107. /* <Description> */
  108. /* A callback function provided by client applications. It is used */
  109. /* to translate a given @FTC_FaceID into a new valid @FT_Face object. */
  110. /* */
  111. /* <Input> */
  112. /* face_id :: The face ID to resolve. */
  113. /* */
  114. /* library :: A handle to a FreeType library object. */
  115. /* */
  116. /* data :: Application-provided request data. */
  117. /* */
  118. /* <Output> */
  119. /* aface :: A new @FT_Face handle. */
  120. /* */
  121. /* <Return> */
  122. /* FreeType error code. 0 means success. */
  123. /* */
  124. /* <Note> */
  125. /* The face requester should not perform funny things on the returned */
  126. /* face object, like creating a new @FT_Size for it, or setting a */
  127. /* transformation through @FT_Set_Transform! */
  128. /* */
  129. typedef FT_Error
  130. (*FTC_Face_Requester)( FTC_FaceID face_id,
  131. FT_Library library,
  132. FT_Pointer request_data,
  133. FT_Face* aface );
  134. /*************************************************************************/
  135. /* */
  136. /* <Struct> */
  137. /* FTC_FontRec */
  138. /* */
  139. /* <Description> */
  140. /* A simple structure used to describe a given `font' to the cache */
  141. /* manager. Note that a `font' is the combination of a given face */
  142. /* with a given character size. */
  143. /* */
  144. /* <Fields> */
  145. /* face_id :: The ID of the face to use. */
  146. /* */
  147. /* pix_width :: The character width in integer pixels. */
  148. /* */
  149. /* pix_height :: The character height in integer pixels. */
  150. /* */
  151. typedef struct FTC_FontRec_
  152. {
  153. FTC_FaceID face_id;
  154. FT_UShort pix_width;
  155. FT_UShort pix_height;
  156. } FTC_FontRec;
  157. /* */
  158. #define FTC_FONT_COMPARE( f1, f2 ) \
  159. ( (f1)->face_id == (f2)->face_id && \
  160. (f1)->pix_width == (f2)->pix_width && \
  161. (f1)->pix_height == (f2)->pix_height )
  162. #define FT_POINTER_TO_ULONG( p ) ((FT_ULong)(FT_Pointer)(p))
  163. #define FTC_FACE_ID_HASH( i ) \
  164. ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \
  165. ( FT_POINTER_TO_ULONG( i ) << 7 ) ) )
  166. #define FTC_FONT_HASH( f ) \
  167. (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
  168. ((f)->pix_width << 8) ^ \
  169. ((f)->pix_height) )
  170. /*************************************************************************/
  171. /* */
  172. /* <Type> */
  173. /* FTC_Font */
  174. /* */
  175. /* <Description> */
  176. /* A simple handle to an @FTC_FontRec structure. */
  177. /* */
  178. typedef FTC_FontRec* FTC_Font;
  179. /*************************************************************************/
  180. /*************************************************************************/
  181. /*************************************************************************/
  182. /***** *****/
  183. /***** CACHE MANAGER OBJECT *****/
  184. /***** *****/
  185. /*************************************************************************/
  186. /*************************************************************************/
  187. /*************************************************************************/
  188. /*************************************************************************/
  189. /* */
  190. /* <Type> */
  191. /* FTC_Manager */
  192. /* */
  193. /* <Description> */
  194. /* This object is used to cache one or more @FT_Face objects, along */
  195. /* with corresponding @FT_Size objects. */
  196. /* */
  197. typedef struct FTC_ManagerRec_* FTC_Manager;
  198. /*************************************************************************/
  199. /* */
  200. /* <Type> */
  201. /* FTC_Node */
  202. /* */
  203. /* <Description> */
  204. /* An opaque handle to a cache node object. Each cache node is */
  205. /* reference-counted. A node with a count of 0 might be flushed */
  206. /* out of a full cache whenever a lookup request is performed. */
  207. /* */
  208. /* If you lookup nodes, you have the ability to "acquire" them, i.e., */
  209. /* to increment their reference count. This will prevent the node */
  210. /* from being flushed out of the cache until you explicitly "release" */
  211. /* it (see @FTC_Node_Release). */
  212. /* */
  213. /* See also @FTC_BitsetCache_Lookup and @FTC_ImageCache_Lookup. */
  214. /* */
  215. typedef struct FTC_NodeRec_* FTC_Node;
  216. /*************************************************************************/
  217. /* */
  218. /* <Function> */
  219. /* FTC_Manager_New */
  220. /* */
  221. /* <Description> */
  222. /* Creates a new cache manager. */
  223. /* */
  224. /* <Input> */
  225. /* library :: The parent FreeType library handle to use. */
  226. /* */
  227. /* max_faces :: Maximum number of faces to keep alive in manager. */
  228. /* Use 0 for defaults. */
  229. /* */
  230. /* max_sizes :: Maximum number of sizes to keep alive in manager. */
  231. /* Use 0 for defaults. */
  232. /* */
  233. /* max_bytes :: Maximum number of bytes to use for cached data. */
  234. /* Use 0 for defaults. */
  235. /* */
  236. /* requester :: An application-provided callback used to translate */
  237. /* face IDs into real @FT_Face objects. */
  238. /* */
  239. /* req_data :: A generic pointer that is passed to the requester */
  240. /* each time it is called (see @FTC_Face_Requester). */
  241. /* */
  242. /* <Output> */
  243. /* amanager :: A handle to a new manager object. 0 in case of */
  244. /* failure. */
  245. /* */
  246. /* <Return> */
  247. /* FreeType error code. 0 means success. */
  248. /* */
  249. FT_EXPORT( FT_Error )
  250. FTC_Manager_New( FT_Library library,
  251. FT_UInt max_faces,
  252. FT_UInt max_sizes,
  253. FT_ULong max_bytes,
  254. FTC_Face_Requester requester,
  255. FT_Pointer req_data,
  256. FTC_Manager *amanager );
  257. /*************************************************************************/
  258. /* */
  259. /* <Function> */
  260. /* FTC_Manager_Reset */
  261. /* */
  262. /* <Description> */
  263. /* Empties a given cache manager. This simply gets rid of all the */
  264. /* currently cached @FT_Face and @FT_Size objects within the manager. */
  265. /* */
  266. /* <InOut> */
  267. /* manager :: A handle to the manager. */
  268. /* */
  269. FT_EXPORT( void )
  270. FTC_Manager_Reset( FTC_Manager manager );
  271. /*************************************************************************/
  272. /* */
  273. /* <Function> */
  274. /* FTC_Manager_Done */
  275. /* */
  276. /* <Description> */
  277. /* Destroys a given manager after emptying it. */
  278. /* */
  279. /* <Input> */
  280. /* manager :: A handle to the target cache manager object. */
  281. /* */
  282. FT_EXPORT( void )
  283. FTC_Manager_Done( FTC_Manager manager );
  284. /*************************************************************************/
  285. /* */
  286. /* <Function> */
  287. /* FTC_Manager_Lookup_Face */
  288. /* */
  289. /* <Description> */
  290. /* Retrieves the @FT_Face object that corresponds to a given face ID */
  291. /* through a cache manager. */
  292. /* */
  293. /* <Input> */
  294. /* manager :: A handle to the cache manager. */
  295. /* */
  296. /* face_id :: The ID of the face object. */
  297. /* */
  298. /* <Output> */
  299. /* aface :: A handle to the face object. */
  300. /* */
  301. /* <Return> */
  302. /* FreeType error code. 0 means success. */
  303. /* */
  304. /* <Note> */
  305. /* The returned @FT_Face object is always owned by the manager. You */
  306. /* should never try to discard it yourself. */
  307. /* */
  308. /* The @FT_Face object doesn't necessarily have a current size object */
  309. /* (i.e., face->size can be 0). If you need a specific `font size', */
  310. /* use @FTC_Manager_Lookup_Size instead. */
  311. /* */
  312. /* Never change the face's transformation matrix (i.e., never call */
  313. /* the @FT_Set_Transform function) on a returned face! If you need */
  314. /* to transform glyphs, do it yourself after glyph loading. */
  315. /* */
  316. FT_EXPORT( FT_Error )
  317. FTC_Manager_Lookup_Face( FTC_Manager manager,
  318. FTC_FaceID face_id,
  319. FT_Face *aface );
  320. /*************************************************************************/
  321. /* */
  322. /* <Function> */
  323. /* FTC_Manager_Lookup_Size */
  324. /* */
  325. /* <Description> */
  326. /* Retrieves the @FT_Face and @FT_Size objects that correspond to a */
  327. /* given @FTC_SizeID. */
  328. /* */
  329. /* <Input> */
  330. /* manager :: A handle to the cache manager. */
  331. /* */
  332. /* size_id :: The ID of the `font size' to use. */
  333. /* */
  334. /* <Output> */
  335. /* aface :: A pointer to the handle of the face object. Set it to */
  336. /* zero if you don't need it. */
  337. /* */
  338. /* asize :: A pointer to the handle of the size object. Set it to */
  339. /* zero if you don't need it. */
  340. /* */
  341. /* <Return> */
  342. /* FreeType error code. 0 means success. */
  343. /* */
  344. /* <Note> */
  345. /* The returned @FT_Face object is always owned by the manager. You */
  346. /* should never try to discard it yourself. */
  347. /* */
  348. /* Never change the face's transformation matrix (i.e., never call */
  349. /* the @FT_Set_Transform function) on a returned face! If you need */
  350. /* to transform glyphs, do it yourself after glyph loading. */
  351. /* */
  352. /* Similarly, the returned @FT_Size object is always owned by the */
  353. /* manager. You should never try to discard it, and never change its */
  354. /* settings with @FT_Set_Pixel_Sizes or @FT_Set_Char_Size! */
  355. /* */
  356. /* The returned size object is the face's current size, which means */
  357. /* that you can call @FT_Load_Glyph with the face if you need to. */
  358. /* */
  359. FT_EXPORT( FT_Error )
  360. FTC_Manager_Lookup_Size( FTC_Manager manager,
  361. FTC_Font font,
  362. FT_Face *aface,
  363. FT_Size *asize );
  364. FT_END_HEADER
  365. #endif /* __FTCACHE_H__ */
  366. /* END */