From ygz@cs.purdue.edu Wed Jun 16 16:53:46 1993 Return-Path: Date: Wed, 16 Jun 1993 16:48:53 -0500 From: ygz@cs.purdue.edu (Yongguang Zhang) To: soft-authors@ifcss.org Subject: comments on HBF APIs Status: O Hi, Here is my comment on Ross' API and MC's API (as in HBF Std 1.0). It is no good to keep two sets of APIs. We should try to merge them. 1. On naming convention. I can accept either set of conventions. I don't think it is an important issue as long as the naming are consistent among themselves. 2. Ross added some useful functions and macros, we should adopt them. 3. On whether to return error status, or to return a pointer in OpenFont call. Ross argued that one can always run my script to get informative diagnostics. I disagree. There are many possible run time problems that cannot be predicted using statical diagnostics. For example, the font name given to OpenFont is misspelled; the bitmap file is misplaced, etc. You cannot require an end-user to run some diagnostics each time the program fails to open a font. Some simple error report is helpful. If we adopt Ross' scheme, some global variable "hbf_error" may be needed. 4. On whether the HBF structure should be hidden. If not, as in Ross scheme, the whole structure has to be included in hbf.h: typedef struct { /* information about the fonts */ ... /* implementation details */ ... } HBF; There is one disadvantage of this. Only the information about the font (e.g., BBXs), but also some implementation bookkeeping information has to be kept in HBF, such as the open file descriptor (for the bitmap file). The information about the font will not change, but the bookkeeping states differs in different implementation. For example, if I write an API that caches the font bitmaps, I have to put a lot more fields in the HBF structure for the cache management. The question is, do I want the application programmer know all these. How about we still define HBF as an integer and use the following function to replace Ross' hbfBitmapBBox or MC's HBF_Get*BoundingBox? const HBF_INFO *hbfInfo (HBF hbf) where typedef struct { /* only the information about the fonts (including the bitmap BBX, etc.) */ ... } HBF_INFO Has anyone actually program using either of the API? We would like to hear more empirical experiences. --ygz From rap@doc.ic.ac.uk Thu Jun 17 06:08:22 1993 Return-Path: Date: Thu, 17 Jun 93 10:31 BST From: Ross Paterson To: soft-authors@ifcss.org Subject: Re: comments on HBF APIs Cc: ygz@cs.purdue.edu Status: O > Here is my comment on Ross' API and MC's API (as in HBF Std 1.0). > It is no good to keep two sets of APIs. We should try to merge them. I've placed a revised version of my code in ifcss.org:incoming/hbf.tar.Z -- it supports both interfaces so folks can experiment. (As another experiment, I've put in that "sideways" feature I was talking about, but I can easily rip that out.) There are also a couple of little programs: tester - a simple black-box test program: prints one bitmap hbfcmp - compare the bitmaps of two fonts described by HBF files hbftobdf - convert an HBF file to the X Windows BDF format (I'm not sure about SWIDTH - can anyone help?) Also, I now like the way GetBitmap() used to be defined in 1.0.3: returning a pointer to the bitmap that's valid until the next call on the same file. It saves having an extra global pointer for each HBF file that is malloc'ed just after the open and used with the appropriate descriptor by GetBitmap(). The answer to Tee Luns's objection last time (it won't work with threads) is that each thread should have its own descriptor -- some implementations (e.g. ones that keep an open FILE, like mine) are not re-entrant and will foul up anyway if shared. The other objection, of course, is that an int return allows more error information. > 3. On whether to return error status, or to return a pointer in > OpenFont call. Ross argued that one can always run my script to get > informative diagnostics. I disagree. There are many possible run > time problems that cannot be predicted using statical diagnostics. > For example, the font name given to OpenFont is misspelled; the > bitmap file is misplaced, etc. You cannot require an end-user to > run some diagnostics each time the program fails to open a font. > Some simple error report is helpful. If Open() fails in an application, the application can report the HBF file name it used. Surely a diagnostic program can perform complete checks given that name, and such a program can give much more precise error information. A helpful application might suggest running the diagnostic, or might even invoke the diagnostic for the user. > If we adopt Ross' scheme, some global variable "hbf_error" may > be needed. Unfortunately this really will mess up threads. > 4. On whether the HBF structure should be hidden. If not, as in Ross > scheme, the whole structure has to be included in hbf.h: > typedef struct { > /* information about the fonts */ > ... > /* implementation details */ > ... > } HBF; > There is one disadvantage of this. Only the information about the > font (e.g., BBXs), but also some implementation bookkeeping > information has to be kept in HBF, such as the open file descriptor > (for the bitmap file). The information about the font will not change, > but the bookkeeping states differs in different implementation. > For example, if I write an API that caches the font bitmaps, I have > to put a lot more fields in the HBF structure for the cache management. > The question is, do I want the application programmer know all these. I agree. In my original implementation, I only showed the part of the structure containing the BBOXs to the application, casting the pointer to the full structure inside the library. In any case, the interface definition (i.e. the manual, not the header file) shouldn't say what's inside the structure -- though a C header file is obliged to give some information, it should be regarded as system-dependent, much like stdio, where there is a type FILE with access routines and macros, but the manual doesn't tell you about use the fields in the stdio.h and you're not supposed use them. Ross From CAI@neurophys.wisc.edu Thu Jun 17 09:43:59 1993 Return-Path: Date: Thu, 17 Jun 93 09:32 CST From: CAI@neurophys.wisc.edu Subject: Re: comments on API To: soft-authors@ifcss.org X-Vms-To: IN%"soft-authors@ifcss.org" Status: O From: IN%"rap@doc.ic.ac.UK" "Ross Paterson" 17-JUN-1993 06:05:07.36 > 3. On whether to return error status, or to return a pointer in > OpenFont call. Ross argued that one can always run my script to get > informative diagnostics. I disagree. There are many possible run > time problems that cannot be predicted using statical diagnostics. > For example, the font name given to OpenFont is misspelled; the > bitmap file is misplaced, etc. You cannot require an end-user to > run some diagnostics each time the program fails to open a font. > Some simple error report is helpful. If Open() fails in an application, the application can report the HBF file name it used. Surely a diagnostic program can perform complete checks given that name, and such a program can give much more precise error information. A helpful application might suggest running the diagnostic, or might even invoke the diagnostic for the user. ---- I don't think it is a good idea to run ygz's script when an application is in progress and an error is encountered. Even if the script reported specific error, one may have to stop the application to fix the bug, and the added complexity may not be justified. By the way, ygz's script is difficult to run on VMS. As a user on vms, I would like to see the unix-based API can be adopted by vms with no or minimum change. Yidao Cai From CAI@neurophys.wisc.edu Thu Jun 17 10:14:12 1993 Return-Path: Date: Thu, 17 Jun 93 10:03 CST From: CAI@neurophys.wisc.edu Subject: What does HBF stand for ? To: soft-authors@ifcss.org X-Vms-To: IN%"soft-authors@ifcss.org" Status: O It seems a silly question to ask, but it is exactly a question I encountered when I am trying to write a short article about HBF for HXWZ. By the title Hanzi Bitmap Font (HBF) File Format Standard Version 1.0 -------------------------------------------------------- it is clear HBF stands for "Hanzi Bitmap Font". But if we look at the subjest title MC Pong used to mail out V1.0 From: IN%"mcpong@cs.ust.hk" 30-APR-1993 07:49:13.39 Subj: HBF Std 1.0 draft 0.4 *********** it is also clear that we actually implied that HBF also stands for "Hanzi Bitmap Font File Format" or "HBF file format" can be shortened as HBF, in case of no ambiguilty. Does everybody agree? Yidao Cai From @skule.ecf.toronto.edu:tee@ecf.toronto.edu Thu Jun 24 15:31:23 1993 Return-Path: <@skule.ecf.toronto.edu:tee@ecf.toronto.edu> From: TEE LUNS To: soft-authors@ifcss.org Subject: Re: comments on HBF APIs Date: Thu, 24 Jun 1993 16:04:29 -0400 Status: RO >Ross Paterson writes: >Also, I now like the way GetBitmap() used to be defined in 1.0.3: >returning a pointer to the bitmap that's valid until the next call on the >same file. It saves having an extra global pointer for each HBF file that >is malloc'ed just after the open and used with the appropriate descriptor >by GetBitmap(). The answer to Tee Luns's objection last time (it won't >work with threads) is that each thread should have its own descriptor -- >some implementations (e.g. ones that keep an open FILE, like mine) are >not re-entrant and will foul up anyway if shared. The other objection, >of course, is that an int return allows more error information. Different threads working on the same document shouldn't have to open their own descriptors to the same font. The old GetBitmap() definition is workable in a multi-thread environment, but would involve throwing in more code to determine which thread the call is being made from, and from that in turn, pick which buffer to pass a bitmap out with. When these buffers get allocated/deallocated becomes undetermined though, so one would be inviting memory leaks unless new calls were introduced. Those would be no better than having to malloc/free everything the way it is now. As for re-entrancy, that's implementation dependant, but I don't think that because one implementation is non re-entrant should we make the API such that a re-entrant implementation is impossible. Re-entrancy is not difficult, so long as we have an API that allows it. Oh, another point: As long as you use GetBitmap() with a global pointer, then yes, it's not any better than the old GetBitmap(). But the point of the copy out is to let you localize the pointer so that different threads don't step over each other's toes when getting bitmaps - i.e. your pointer would be an automatic variable. > If Open() fails in an application, the application can report the HBF >file name it used. Surely a diagnostic program can perform complete >checks given that name, and such a program can give much more precise >error information. A helpful application might suggest running the >diagnostic, or might even invoke the diagnostic for the user. But would not it be nice to be able to tell the user what was wrong with the HBF file at the same time? Being able to distinguish if a bad filename was given, or a bitmap is missing without having to go and run a seperate program seems like enough of a convenience to make up for having to pass a pointer. >to the full structure inside the library. In any case, the interface >definition (i.e. the manual, not the header file) shouldn't say what's >inside the structure -- though a C header file is obliged to give some >information, it should be regarded as system-dependent, much like stdio, >where there is a type FILE with access routines and macros, but the >manual doesn't tell you about use the fields in the stdio.h and you're >not supposed use them. I agree that the structure should be treated as a magic cookie in documentation, but I thought I'd point out that it is possible to carry into the headers. You can actually getting away without having to reveal any of the structure's internals in the header files, if you're willing to give up having macros that go in and get data directly. In particular, your header file can have typedef struct _hbf HBF; and nothing more about the data structure. As long as all references to HBF are by pointers, and don't refer to its members, the compiler is quite happy to know nothing about what's inside. In the source for the library of course, you'd have to give the full structure, but that goes without saying. Whether to take this approach or expose the whole structure with the programmer's promise of treating it as a magic cookie is debatable, but it's no longer a concern of the standard. Luns