1 /* $XConsortium: objects.c,v 1.11 94/03/23 14:28:05 gildea Exp $ */
2 /* Copyright International Business Machines, Corp. 1991
3 * All Rights Reserved
4 * Copyright Lexmark International, Inc. 1991
5 * All Rights Reserved
6 *
7 * License to use, copy, modify, and distribute this software and its
8 * documentation for any purpose and without fee is hereby granted,
9 * provided that the above copyright notice appear in all copies and that
10 * both that copyright notice and this permission notice appear in
11 * supporting documentation, and that the name of IBM or Lexmark not be
12 * used in advertising or publicity pertaining to distribution of the
13 * software without specific, written prior permission.
14 *
15 * IBM AND LEXMARK PROVIDE THIS SOFTWARE "AS IS", WITHOUT ANY WARRANTIES OF
16 * ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO ANY
17 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
18 * AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE RISK AS TO THE
19 * QUALITY AND PERFORMANCE OF THE SOFTWARE, INCLUDING ANY DUTY TO SUPPORT
20 * OR MAINTAIN, BELONGS TO THE LICENSEE. SHOULD ANY PORTION OF THE
21 * SOFTWARE PROVE DEFECTIVE, THE LICENSEE (NOT IBM OR LEXMARK) ASSUMES THE
22 * ENTIRE COST OF ALL SERVICING, REPAIR AND CORRECTION. IN NO EVENT SHALL
23 * IBM OR LEXMARK BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
24 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
25 * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
26 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
27 * THIS SOFTWARE.
28 */
29 /* OBJECTS CWEB V0025 ******** */
30 /*
31 :h1.OBJECTS Module - TYPE1IMAGER Objects Common Routines
32
33 This module defines and implements the C structures that represent
34 objects in the TYPE1IMAGER. All common routines for manipulating these
35 objects are defined in this module. Specific routines for
36 specific objects are defined in the modules that deal with that
37 object type.
38
39
40 &author. Jeffrey B. Lotspiech (lotspiech@almaden.ibm.com)
41
42
43 :h3.Include Files
44
45 The included files are:
46 */
47 #define GLOBALS 1 /* see :hdref refid=debugvar. */
48 /*
49 The following two includes are C standards; we include them because we
50 use 'toupper' and the 'str'-type functions in this module. Potentially
51 these may be defined as macros; if these ".h" files do not exist on your
52 system it is a pretty safe bet that these are external entry points and
53 you do do not need to include these header files.
54 */
55
56 #include <string.h>
57 #include <ctype.h>
58
59 /*
60 override incorrect system functions; for example you might define
61 a macro for "strcpy" that diverts it to "my_strcpy".
62 */
63
64 /* moved these includes from above the */
65 /* was included first (it contains com- */
66 /* piler defines). dsr 081291 */
67 #include "objects.h"
68 #include "spaces.h"
69 #include "paths.h"
70 #include "regions.h"
71 #include "fonts.h"
72 #include "pictures.h"
73 #include "strokes.h"
74 #include "cluts.h"
75 static char *TypeFmt();
76 static ObjectPostMortem();
77
78 /*
79 :h3.The "pointer" Macro - Define a Generic Pointer
80
81 Sadly, many compilers will give a warning message when a pointer to
82 one structure is assigned to a pointer to another. We've even seen
83 some that give severe errors (when the wrong pointer type is used as
84 an initializer or returned from a function). TYPE1IMAGER has routines
85 like Dup and Allocate that are perfectly willing to duplicate or
86 allocate any of a number of different types of structures. How to
87 declare them in a truely portable way?
88
89 Well, there is no single good answer that I've found. You can always
90 beg the question and "cast" everything. I find this distracting and the
91 resulting code ugly. On the other hand, we have found at least one
92 compiler that will accept "void *" as a generic pointer that can
93 assigned to any other pointer type without error or warning (apparently
94 this is also the ANSI standard). So, we define "void *" to be a generic
95 pointer. (You might have to change this for your compiler; the "ifndef"
96 allows the change to be made on the command line if you want.)
97 :i1/portability assumptions/
98 */
99 /*SHARED LINE(S) ORIGINATED HERE*/
100 /*
101 :h3.Functions Provided to the TYPE1IMAGER User
102
103 This module provides the following TYPE1IMAGER entry points:
104 */
105 /*SHARED LINE(S) ORIGINATED HERE*/
106 /*
107 Note that entry points that are intended for use external to TYPE1IMAGER
108 begin with the characters :q/xi/. Macros are used to make the names
109 more mnemonic.
110 */
111
112 /*
113 :h3.Functions Provided to Other Modules
114
115 This module provides the following functions for other modules:
116 */
117 /*SHARED LINE(S) ORIGINATED HERE*/
118 /*
119 Note that entry points that intended for use within TYPE1IMAGER, but
120 which must be global because they are used across module boundaries,
121 begin with the characters :q/I_/. Macros are used to make the names
122 more mnemonic.
123
124 Entry points totally within a module use mnemonic names and are
125 declared :hp2/static/. One of the compilers I used had a bug when
126 static functions were passed as addresses. Thus, some functions
127 which are logically "static" are not so declared.
128
129 Note also the trick of declaring routines, like Consume(), with a
130 variable number of arguments. To avoid the restrictions on variable
131 numbers of arguments in the macro processor, we just replace the
132 text 'Consume' with 'I_Consume'.
133 */
134 /*
135 :h3.Macros Provided to Other Modules
136
137 This is the module where we define all the useful constants like
138 TRUE, FALSE, and NULL, and simple expressions like MIN(), MAX(), and ABS().
139 We might as well get to it right here:
140 */
141 /*SHARED LINE(S) ORIGINATED HERE*/
142 /*
143 Notice that upper case is used for constant values and macro
144 definitions. I generally follow that convention.
145
146 Many more global macros are defined later in this module.
147 */
148 /*
149 :h2.Basic TYPE1IMAGER Object Structure
150
151 All TYPE1IMAGER objects which are available to the user have a common
152 header. This header is defined below:
153 */
154
155 /*SHARED LINE(S) ORIGINATED HERE*/
156 /*
157 The following define is an attempt to centralize the definition of the
158 common xobject data shared by structures that are derived from the
159 generic xobject structure. For example, the structure font, defined in
160 fonts.shr :
161 &code.
162 struct font {
163 char type;
164 char flag;
165 int references;
166 ... other data types & structs ...
167 }
168 &ecode.
169 would now be defined as:
170 &code.
171 struct font {
172 XOBJ_COMMON
173 ... other data types & structs ...
174 }
175 &ecode.
176 Thus we have a better-structured inheritance mechanism. 3-26-91 PNM
177 */
178 /*SHARED LINE(S) ORIGINATED HERE*/
179 /*
180 :h3.Object Type Definitions
181
182 These constants define the values which go in the 'type' field of
183 an TYPE1IMAGER object structure:
184 */
185 /*SHARED LINE(S) ORIGINATED HERE*/
186 /*
187 :h3.Flag Byte Definitions
188
189 Many programmers define flag bits as a mask (for example, 0x04), and
190 test, set, and reset them as follows:
191
192 &code.
193 if ((flag & PERMANENT) != 0)
194
195 flag |= PERMANENT;
196 flag &= &inv.PERMANENT;
197 :exmp.
198
199 I favor a style where the 'if' statement can ask a question:
200
201 &code.
202 if (ISPERMANENT(flag))
203
204 flag |= ISPERMANENT(ON);
205 flag &= &inv.ISPERMANENT(ON);
206
207 :exmp.
208 This said, we now define two bit settings of the flag byte of the
209 object. "ISPERMANENT" will be set by the user, when he calls
210 Permanent(). "ISIMMORTAL" will be used for compiled-in objects
211 that we don't want the user to ever destroy.
212 */
213 /*SHARED LINE(S) ORIGINATED HERE*/
214 /*
215 Flag bit definitions that apply to all objects are assigned
216 starting with the least significant (0x01) bit. Flag bit definitions
217 specific to a certain object type are assigned starting with the
218 most significant (0x80) bit. We hope they never meet.
219 */
220 /*
221 :h3 id=preserve.PRESERVE() Macro
222
223 Occasionally an TYPE1IMAGER operator is implemented by calling other
224 TYPE1IMAGER operators. For example, Arc2() calls Conic(). When we
225 call more than one operator as a subroutine, we have to be careful
226 of temporary objects. A temporary object will be consumed by the
227 subroutine operator and then is no longer available for the caller.
228 This can be prevented simply by bumping a temporary object's reference
229 count.
230 */
231 /*SHARED LINE(S) ORIGINATED HERE*/
232
233 /*
234 :h3.RefRoll() Macro to Detect References Count Rollover
235
236 The following macro is designed to check for reference count rollover.
237 A return value of TRUE means rollover has not occurred; a return value
238 of FALSE means we cannot increment the reference count. Note also that
239 those functions that use this macro must decrement the reference count
240 afterwards. 3-26-91 PNM
241 */
242
243 #define RefRoll(obj) (++(obj)->references > 0)
244
245 /*
246 :h2.TYPE1IMAGER Object Functions
247
248 :h3.LONGCOPY() - Macro to Copy "long" Aligned Data
249
250 Copying arbitrary bytes in C is a bit of a problem. "strcpy" can't be
251 used, because 0 bytes are special-cased. Most environments have a
252 routine "memcopy" or "bcopy" or "bytecopy" that copies memory containing
253 zero bytes. Sadly, there is no standard on the name of such a routine,
254 which makes it impossible to write truely portable code to use it.
255
256 It turns out that TYPE1IMAGER, when it wants to copy data, frequently
257 knows that both the source and destination are aligned on "long"
258 boundaries. This allows us to copy by using "long *" pointers. This
259 is usually very efficient on almost all processors. Frequently, it
260 is more efficient than using general-purpose assembly language routines.
261 So, we define a macro to do this in a portable way. "dest" and "source"
262 must be long-aligned, and "bytes" must be a multiple of "sizeof(long)":
263 */
264 /*SHARED LINE(S) ORIGINATED HERE*/
265 /*
266 :h3.Allocate() - Allocating a Memory Block
267
268 Allocate returns a pointer to memory object that is a copy of
269 the template passed (if any). In addition, extra bytes may be
270 allocated contiguously with the object. (This may be useful for
271 variable size objects such as edge lists. See :hdref refid=regions..)
272
273 Allocate() always returns a non-immortal object, even if the template is
274 immortal. Therefore a non-NULL template must have a "flag" byte.
275
276 If the template is NULL, then 'size' bytes are cleared to all NULLs.
277
278 If the template is non-NULL, a new object is allocated in memory.
279 It therefore seems logical that its reference count field should be
280 set to 1. So, a nun-NULL template must also have a "references" field.
281 PNM 3-26-91
282 */
283
t1_Allocate(size,template,extra)284 struct xobject *t1_Allocate(size, template, extra) /* non-ANSI; type checking was too strict */
285 register int size; /* number of bytes to allocate & initialize */
286 register struct xobject *template; /* example structure to allocate */
287 register int extra; /* any extra uninitialized bytes needed contiguously */
288 {
289 extern char *xiMalloc(); /* standard C routine */
290
291 register struct xobject *r;
292
293 /*
294 * round up 'size' and 'extra' to be an integer number of 'long's:
295 */
296 size = (size + sizeof(long) - 1) & -(int)sizeof(long);
297 extra = (extra + sizeof(long) - 1) & -(int)sizeof(long);
298 if (size + extra <= 0)
299 abort("Non-positive allocate?");
300 r = (struct xobject *) xiMalloc(size + extra);
301
302 while (r == NULL) {
303 if (!GimeSpace()) {
304 IfTrace1(TRUE, "malloc attempted %d bytes.\n",
305 size + extra);
306 abort("We have REALLY run out of memory");
307 }
308 r = (struct xobject *) xiMalloc(size + extra);
309 }
310
311 /*
312 * copy the template into the new memory:
313 */
314 if (template != NULL) {
315 /* Added references count decrement if template is not permanent.
316 This is for the case where Allocate is called by a Dupxxxx
317 function, which was in turn called by Unique(). (PNM) */
318 if (!ISPERMANENT(template->flag))
319 --template->references;
320 LONGCOPY(r, template, size);
321 r->flag &= ~(ISPERMANENT(ON) | ISIMMORTAL(ON));
322 /* added reference field 3-2-6-91 PNM */
323 r->references = 1;
324 }
325 else {
326 register char **p1;
327
328 for (p1=(char **)r; size > 0; size -= sizeof(char *))
329 *p1++ = NULL;
330 }
331
332 if (MemoryDebug > 1) {
333 register long *L;
334 L = (long *) r;
335 IfTrace4(TRUE, "Allocating at %x: %x %x %x\n",
336 L, L[-1], L[0], L[1]);
337 }
338 return(r);
339 }
340
341 /*
342 :h3.Free() - Frees an Allocated Object
343
344 This routine makes a sanity check to make sure the "type" field of the
345 standard object structure has not been cleared. If the object is
346 not a standard structure, then the macro "NonObjectFree" is available
347 that does not perform this check.
348
349 In either case, the object must not be the NULL pointer. This preserves
350 portability, as the C system xiFree() will not always accept NULL.
351 */
352
Free(obj)353 void Free(obj) /* non-ANSI to avoid overly strict type checking */
354 register struct xobject *obj; /* structure to free */
355 {
356 if (obj->type == INVALIDTYPE)
357 abort("Free of already freed object?");
358 obj->type = INVALIDTYPE;
359
360 if (MemoryDebug > 1) {
361 register long *L;
362 L = (long *) obj;
363 IfTrace4(TRUE,"Freeing at %x: %x %x %x\n", L, L[-1], L[0], L[1]);
364 }
365
366 xiFree(obj);
367 }
368
369 /*
370 :h3.Permanent() - Makes an Object Permanent
371
372 Real simple--just set a flag. Every routine that consumes its objects
373 (which is almost every user entry) must check this flag, and not consume
374 the object if it is set.
375
376 If a temporary object is made permanent, and there is more than one
377 reference to it, we must first Copy() it, then set the ISPERMANENT
378 flag. Note also that the reference count must be incremented when an
379 object is changed from temporary to permanent (see the ISUNIQUE macro).
380
381 Note that the purpose of this function is to convert an object into a
382 permanent object:
383 If it was permanent to begin with, we do nothing;
384 If it was temporary and unique, we set the PERMANENT flag and increment
385 the reference count;
386 If it was temporary and nonunique, we must make a unique Copy(), set
387 the PERMANENT flag, and set the reference count to 2. We must also
388 decrement the original object's reference count, because what we have
389 done is to change one of the old temporary handles to a permanent one.
390 3-26-91 PNM
391 */
392
t1_Permanent(obj)393 struct xobject *t1_Permanent(obj) /* non-ANSI to avoid overly strict type checking */
394 register struct xobject *obj; /* object to be made permanent */
395 {
396 IfTrace1((MustTraceCalls),"Permanent(%z)\n", obj);
397
398 if ( (obj != NULL) && ( !(ISPERMANENT(obj->flag)) ) )
399 {
400 /* there is a non-NULL, temporary object to be made permanent.
401 If there are multiple references to this object, first get
402 a new COPY().
403 Note also that we have to decrement the reference count if
404 we do a Copy() here, because we are consuming the temporary
405 argument passed, and returning a unique, permanent one.
406 */
407 if ( obj->references > 1)
408 {
409 obj = Copy(obj);
410 }
411 /* now set the permanent flag, and increment the reference
412 count, since a temporary object has now become permanent. */
413 obj->references++;
414 obj->flag |= ISPERMANENT(ON);
415 }
416 return(obj);
417 }
418
419 /*
420 :h3.Temporary() - Undoes the Effect of "Permanent()"
421
422 This simply resets the "ISPERMANENT" flag.
423
424 If a permanent object is made temporary, and there is more than one reference
425 to it, we must first Copy() it, then reset the ISPERMANENT flag. However,
426 if the permanent object has obly one reference, we need only decrement the
427 reference count ( and reset the flag).
428
429 Note that this function, in the case of a PERMANENT argument, basically
430 converts the PERMANENT handle to a TEMPORARY one. Thus, in the case of
431 a nonunique, permanent argument passed, we not only make a Copy(),
432 we also decrement the reference count, to reflect the fact that we have
433 lost a permanent handle and gained a temporary one.
434 PNM 3-2-6-91
435 */
436
xiTemporary(obj)437 struct xobject *xiTemporary(obj) /* non-ANSI to avoid overly strict type checking */
438 register struct xobject *obj; /* object to be made permanent */
439 {
440 IfTrace1((MustTraceCalls),"Temporary(%z)\n", obj);
441
442 if (obj != NULL) {
443 /* if it's already temporary, there's nothing to do. */
444 if ISPERMANENT(obj->flag)
445 {
446 /* if there are multiple references to this object, get a
447 Copy we can safely alter. Recall that the reference count
448 is incremented for permanent objects.
449 Recall further that Copy returns an object with the
450 same flag state and a reference count of 2 (for PERMANENT
451 objects).
452 Thus, regardless of whether or not we need to copy a
453 permanent object, we still decrement its reference
454 count and reset the flag.
455 */
456 if (obj->references != 2 || ISIMMORTAL(obj->flag))
457 {
458 /* not unique; consume handle, get a temporary Copy! */
459 obj = Copy(obj);
460 }
461 /* else decrement the reference count (since it's going from
462 permanent to temporary) and clear the flag. */
463 else {
464 obj->references--;
465 obj->flag &= ~ISPERMANENT(ON);
466 }
467 }
468 }
469 return(obj);
470 }
471
472 /*
473 :h3.Dup() - Duplicate an Object
474
475 Dup will increment the reference count of an object, only making a
476 Copy() if needed.
477 Note that Dup() retains the state of the permanent flag.
478 3-26-91 PNM
479 */
480
481
t1_Dup(obj)482 struct xobject *t1_Dup(obj) /* non-ANSI avoids overly strict type checking */
483 register struct xobject *obj; /* object to be duplicated */
484 {
485 register char oldflag; /* copy of original object's flag byte */
486
487 IfTrace1((MustTraceCalls),"Dup(%z)\n", obj);
488
489 if (obj == NULL)
490 return(NULL);
491 /* An immortal object must be Copy'ed, so that we get a mortal
492 copy of it, since we try not to destroy immortal objects. */
493 if (ISIMMORTAL(obj->flag))
494 return(Copy(obj));
495
496 /* if incrementing the reference count doesn't cause the count
497 to wrap, simply return the object with the count bumped. Note
498 that the RefRoll macro increments the count to perform the
499 rollover check, so we must decrement the count. */
500 if (RefRoll(obj))
501 return(obj);
502
503 /* that didn't work out, so put the count back and call Copy(). */
504 --obj->references;
505 oldflag = obj->flag;
506 obj = Copy(obj);
507 if (ISPERMANENT(oldflag))
508 obj = Permanent(obj);
509 return(obj);
510 }
511
512 /*
513 :h3.Copy() - Make a New Copy of an Object
514
515 This is the generic Copy() where the object type is unknown. There
516 are specific Copyxxx functions for known object types.
517
518 Copy will create a NEW temporary object, and WILL NOT simply bump the
519 reference count.
520
521 Sometimes duplicating an object is just as simple as Allocating with it
522 as a template. But other objects are complicated linked lists. So, we
523 let each module provide us a routine (or macro) that duplicates the
524 objects it knows about.
525 */
526
t1_Copy(obj)527 struct xobject *t1_Copy(obj)
528 register struct xobject *obj; /* object to be Copy'ed */
529 {
530 if (obj == NULL)
531 return(NULL);
532
533 if (ISPATHTYPE(obj->type))
534 obj = (struct xobject *) CopyPath(obj);
535 else
536 switch (obj->type) {
537 case SPACETYPE:
538 obj = (struct xobject *) CopySpace(obj); break;
539 case FONTTYPE:
540 obj = (struct xobject *) CopyFont(obj); break;
541 case REGIONTYPE:
542 obj = (struct xobject *) CopyRegion(obj); break;
543 case PICTURETYPE:
544 obj = (struct xobject *) CopyPicture(obj); break;
545 case LINESTYLETYPE:
546 obj = (struct xobject *) CopyLineStyle(obj); break;
547 case STROKEPATHTYPE:
548 obj = (struct xobject *) CopyStrokePath(obj); break;
549 case CLUTTYPE:
550 obj = (struct xobject *) CopyCLUT(obj); break;
551 default:
552 return(ArgErr("Copy: invalid object", obj, NULL));
553 }
554
555 return(obj);
556 }
557
558 /*
559 :h3.Destroy() - Destroys an Object
560
561 This can get complicated. Just like with Copy(), we let the experts
562 handle it.
563 */
Destroy(obj)564 struct xobject *Destroy(obj) /* non-ANSI avoids overly strict type checking */
565 register struct xobject *obj; /* object to be destroyed */
566 {
567 IfTrace1((MustTraceCalls),"Destroy(%z)\n", obj);
568
569 if (obj == NULL)
570 return(NULL);
571 if (ISIMMORTAL(obj->flag)) {
572 IfTrace1(TRUE,"Destroy of immortal object %z ignored\n", obj);
573 return(NULL);
574 }
575 if (ISPATHTYPE(obj->type))
576 KillPath(obj);
577 else {
578 switch (obj->type) {
579 case REGIONTYPE:
580 KillRegion(obj);
581 break;
582 case SPACETYPE:
583 KillSpace(obj);
584 break;
585 case LINESTYLETYPE:
586 KillLineStyle(obj);
587 break;
588 case FONTTYPE:
589 KillFont(obj);
590 break;
591 case PICTURETYPE:
592 KillPicture(obj);
593 break;
594 case STROKEPATHTYPE:
595 KillStrokePath(obj);
596 break;
597 case CLUTTYPE:
598 KillCLUT(obj);
599 break;
600 default:
601 return(ArgErr("Destroy: invalid object", obj, NULL));
602 }
603 }
604 return(NULL);
605 }
606 /*
607 :h2.Generally Useful Macros
608
609 :h3.FOLLOWING() - Macro to Point to the Data Following a Structure
610
611 There are several places in TYPE1IMAGER where we will allocate variable
612 data that belongs to a structure immediately after that structure.
613 This is a performance technique, because it reduces the number of
614 trips we have to take through xiMalloc() and xiFree(). It turns out C has
615 a very convenient way to point past a structure--if 'p' is a pointer
616 to a structure, 'p+1' is a pointer to the data after it. This
617 behavior of C is somewhat startling and somewhat hard to follow, if
618 you are not used to it, so we define a macro to point to the data
619 following a structure:
620 */
621 /*SHARED LINE(S) ORIGINATED HERE*/
622 /*
623 :h3.TYPECHECK() - Verify the Type of an Argument
624
625 This macro tests the type of an argument. If the test fails, it consumes
626 any other arguments as necessary and causes the imbedding routine to
627 return the value 'whenBAD'.
628
629 Note that the consumeables list should be an argument list itself, for
630 example (0) or (2,A,B). See :hdref refid=consume. below.
631 */
632
633 /*SHARED LINE(S) ORIGINATED HERE*/
634 /*
635 :h3.ARGCHECK() - Perform an Arbitrary Check on an Argument
636
637 This macro is a generalization of TYPECHECK to take an arbitrary
638 predicate. If the error occurs (i.e., the predicate is true), the
639 arbitrary message 'msg' is returned.
640 */
641
642 /*SHARED LINE(S) ORIGINATED HERE*/
643 /*
644 :h3.TYPENULLCHECK() - Extension of TYPECHECK() for NULL arguments
645
646 Many routines allow NULLs to be passed as arguments. 'whenBAD' will
647 be returned in this case, too.
648 */
649
650 /*SHARED LINE(S) ORIGINATED HERE*/
651 /*
652 :h3.MAKECONSUME() - Create a "Consume"-type Macro
653
654 Consuming an object means destroying it if it is not permanent. This
655 logic is so common to all the routines, that it is immortalized in this
656 macro. For example, ConsumePath(p) can be simply defined as
657 MAKECONSUME(p,KillPath(p)). In effect, this macro operates on a
658 meta-level.
659 :i1/consuming objects/
660 */
661
662 /*SHARED LINE(S) ORIGINATED HERE*/
663
664 /*
665 :h3.MAKEUNIQUE() - Create a "Unique"-type Macro
666
667 Many routines are written to modify their arguments in place. Thus,
668 they want to insure that they duplicate an object if it is permanent.
669 This is called making an object "unique". For example, UniquePath(p)
670 can be simply defined as MAKEUNIQUE(p,DupPath(p)).
671 :i1/unique objects/
672 */
673
674 /*SHARED LINE(S) ORIGINATED HERE*/
675
676 /*
677 An object is unique (and directly alterable) if there is only one
678 reference to it, and it is not permanent (in which case we increment
679 the reference count, so we don't have to check the permanent bit).
680 3-26-91 PNM
681
682 Note the rules for making a unique object:
683 &drawing.
684 IF (obj->references = 1) return(obj);
685 ELSE (references > 1)
686 IF (ISPERMANENT(obj->flag)) return(Dupxxx(obj));
687 ELSE (nonunique, temporary object!)
688 obj->references--; return(Dupxxx(obj));
689 &edrawing.
690 If we must make a Copy of a nonunique, temporary object, we decrement
691 reference count of the original object!
692 */
693
694 /*
695 :h3.Unique() - Make a Unique Object
696
697 Here is a generic 'Unique' function if the object type is not known.
698 Why didn't we build it with the MAKEUNIQUE macro, you ask? Well, we
699 used to, but there is at least one damn compiler in the world that
700 raises errors if the types of an "(a) ? b : c" expression do not match.
701 Also, when we changed Dup() to retain the permanent/temporary flag, we
702 wanted to make sure "Unique" always returned a temporary object.
703
704 Note that we cannot use Dup() to create a copy of the object in question,
705 because Dup() may simply bump the reference count, and not return a
706 unique copy to us. That is why we use t1_Copy().
707
708 The purpose of this function is to make sure we have a copy of an object
709 that we can safely alter:
710 :ol.
711 :li.If we have a unique, temporary object, we simply return the argument.
712 :li.If we have a nonunique, temporary object, we have to make a new copy
713 of it, and decrement the reference count of the original object, to reflect
714 the fact that we traded temporary handles.
715 :li.If we have a permanent object, we make a temporary copy of it, but
716 we do not decrement the reference count of the original permanent object,
717 because permanent objects, by definition, are persistent. 3-2-6-91 PNM
718 :eol.
719 */
720
t1_Unique(obj)721 struct xobject *t1_Unique(obj)
722 struct xobject *obj;
723 {
724 /* if the original object is not already unique, make a unique
725 copy...Note also that if the object was not permanent, we must
726 consume the old handle! 3-26-91 PNM
727 NOTE : consumption of the old handle moved to Allocate. 4-18-91 */
728 if (!obj || obj->references == 1)
729 return(obj);
730
731 obj = Copy(obj);
732 /* and make sure we return a temporary object ! */
733 if (ISPERMANENT(obj->flag))
734 {
735 obj->flag &= ~ISPERMANENT(ON);
736 obj->references--;
737 }
738 return(obj);
739 }
740
741
742 /*
743 :h2.Initialization, Error, and Debug Routines
744
745 :h3 id=debugvar.Declarations for Debug Purposes
746
747 We declare all the debug flags here. Some link editors make the not
748 unreasonable restriction that only one module may declare and
749 initialize global variables; all the rest must declare the variable
750 'extern'. This is logical, but is somewhat awkward to implement with
751 C include files. We solve the problem by temporarily making the name
752 'extern' a null name if GLOBALS is defined. (GLOBALS is only defined
753 in this OBJECTS module.) Since 'externs' can't be initialized, we
754 have to handle that with #defines too.
755 :i1/GLOBALS (&#define.)/
756 */
757
758 /*SHARED LINE(S) ORIGINATED HERE*/
759 static char *ErrorMessage = NULL;
760
761 /*
762 :h3.Pragmatics() - Set/Reset Debug Flags
763
764 We provide a controlled way for the TYPE1IMAGER user to set and reset
765 our debugging and tracing:
766 */
Pragmatics(username,value)767 void Pragmatics(username, value)
768 char *username; /* name of the flag */
769 int value; /* value to set it to */
770 {
771 register char *p; /* temporary loop variable */
772 #define NAMESIZE 40
773 char name[NAMESIZE]; /* buffer to store my copy of 'username' */
774
775 if (strlen(username) >= (unsigned)NAMESIZE)
776 abort("Pragmatics name too large");
777 strcpy(name, username);
778 for (p = name; *p != '\0'; p++)
779 *p = toupper(*p);
780
781 if (!strcmp(name, "ALL"))
782 MustTraceCalls = InternalTrace = /* MustCrash = */
783 LineIOTrace = value;
784
785 else if (!strcmp(name, "LINEIOTRACE"))
786 LineIOTrace = value;
787
788 else if (!strcmp(name, "TRACECALLS"))
789 MustTraceCalls = value;
790
791 else if (!strcmp(name, "CHECKARGS"))
792 MustCheckArgs = value;
793
794 else if (!strcmp(name, "PROCESSHINTS"))
795 ProcessHints = value;
796
797 else if (!strcmp(name, "SAVEFONTPATHS"))
798 SaveFontPaths = value;
799
800 else if (!strcmp(name, "CRASTERCOMPRESSIONTYPE"))
801 CRASTERCompressionType = value;
802
803 else if (!strcmp(name, "CRASHONUSERERROR"))
804 MustCrash = value;
805
806 else if (!strcmp(name, "DEBUG"))
807 StrokeDebug = SpaceDebug = PathDebug = ConicDebug = LineDebug =
808 RegionDebug = MemoryDebug = FontDebug =
809 HintDebug = ImageDebug = OffPageDebug = value;
810
811 else if (!strcmp(name, "CONICDEBUG"))
812 ConicDebug = value;
813
814 else if (!strcmp(name, "LINEDEBUG"))
815 LineDebug = value;
816
817 else if (!strcmp(name, "REGIONDEBUG"))
818 RegionDebug = value;
819
820 else if (!strcmp(name, "PATHDEBUG"))
821 PathDebug = value;
822
823 else if (!strcmp(name, "SPACEDEBUG"))
824 SpaceDebug = value;
825
826 else if (!strcmp(name, "STROKEDEBUG"))
827 StrokeDebug = value;
828
829 else if (!strcmp(name, "MEMORYDEBUG"))
830 MemoryDebug = value;
831
832 else if (!strcmp(name, "FONTDEBUG"))
833 FontDebug = value;
834
835 else if (!strcmp(name, "HINTDEBUG"))
836 HintDebug = value;
837
838 else if (!strcmp(name, "IMAGEDEBUG"))
839 ImageDebug = value;
840
841 else if (!strcmp(name, "OFFPAGEDEBUG"))
842 OffPageDebug = value;
843
844 #ifdef MC68000
845 /*
846 The following pragmatics flag turns on or off instruction histograming
847 for performance analysis. It is only defined in the Delta card
848 environment.
849 */
850 else if (!strcmp(name, "PROFILE")) {
851 if (value)
852 StartProfile();
853 else
854 StopProfile();
855 }
856 #endif
857 else if (!strcmp(name, "FLUSHCACHE")) {
858 #ifdef notdef
859 while (GimeSpace()) { ; }
860 #endif
861 }
862
863 else if (!strcmp(name, "CACHEDCHARS"))
864 CachedChars = (value <= 0) ? 1 : value;
865
866 else if (!strcmp(name, "CACHEDFONTS"))
867 CachedFonts = (value <= 0) ? 1 : value;
868
869 else if (!strcmp(name, "CACHEBLIMIT"))
870 CacheBLimit = value;
871
872 else if (!strcmp(name, "CONTINUITY"))
873 Continuity = value;
874
875
876 else {
877 printf("Pragmatics flag = '%s'\n", name);
878 ArgErr("Pragmatics: flag not known", NULL, NULL);
879 }
880 return;
881 }
882
883 /*
884 :h3.Consume() - Consume a List of Arguments
885
886 This general purpose routine is provided in the case where the object
887 type(s) to be consumed are unknown or not yet verified, and/or it is
888 not known whether the object is permanent.
889
890 If the type of the argument is known, it is faster to directly consume
891 that type, for example, ConsumeRegion() or ConsumePath(). Furthermore,
892 if it is already known that the object is temporary, it is faster to
893 just kill it rather than consume it, for example, KillSpace().
894 */
895
Consume(n,obj1,obj2,obj3)896 void Consume(n, obj1, obj2, obj3) /* non-ANSI avoids overly strict type checking */
897 int n;
898 struct xobject *obj1,*obj2,*obj3;
899 {
900 switch(n) {
901
902 case 0:
903 return;
904
905 case 1:
906 if (obj1 != NULL && !ISPERMANENT(obj1->flag))
907 Destroy(obj1);
908 return;
909
910 case 2:
911 if (obj1 != NULL && !ISPERMANENT(obj1->flag))
912 Destroy(obj1);
913 if (obj2 != NULL && !ISPERMANENT(obj2->flag))
914 Destroy(obj2);
915 return;
916
917 case 3:
918 if (obj1 != NULL && !ISPERMANENT(obj1->flag))
919 Destroy(obj1);
920 if (obj2 != NULL && !ISPERMANENT(obj2->flag))
921 Destroy(obj2);
922 if (obj3 != NULL && !ISPERMANENT(obj3->flag))
923 Destroy(obj3);
924 return;
925
926 default:
927 abort("Consume: too many objects");
928 }
929 }
930 /*
931 :h3.TypeErr() - Handles "Invalid Object Type" Errors
932 */
933
TypeErr(name,obj,expect,ret)934 struct xobject *TypeErr(name, obj, expect, ret) /* non-ANSI avoids overly strict type checking */
935 char *name; /* Name of routine (for error message) */
936 struct xobject *obj; /* Object in error */
937 int expect; /* type expected */
938 struct xobject *ret; /* object to return to caller */
939 {
940 static char typemsg[80];
941
942 if (MustCrash)
943 LineIOTrace = TRUE;
944
945 sprintf(typemsg, "Wrong object type in %s; expected %s.\n",
946 name, TypeFmt(expect), TypeFmt(obj->type));
947 IfTrace0(TRUE,typemsg);
948
949 ObjectPostMortem(obj);
950
951 if (MustCrash)
952 abort("Terminating because of CrashOnUserError...");
953 else
954 ErrorMessage = typemsg;
955
956 /* changed ISPERMANENT to ret->references > 1 3-26-91 PNM */
957 if (ret != NULL && (ret->references > 1))
958 ret = Dup(ret);
959 return(ret);
960 }
961
962 /*
963 :h4.TypeFmt() - Returns Pointer to English Name of Object Type
964
965 This is a subroutine of TypeErr().
966 */
967
TypeFmt(type)968 static char *TypeFmt(type)
969 int type; /* type field */
970 {
971 char *r;
972
973 if (ISPATHTYPE(type))
974 if (type == TEXTTYPE)
975 r = "path or region (from TextPath)";
976 else
977 r = "path";
978 else {
979 switch (type) {
980 case INVALIDTYPE:
981 r = "INVALID (previously consumed?)";
982 break;
983 case REGIONTYPE:
984 r = "region";
985 break;
986 case SPACETYPE:
987 r = "XYspace";
988 break;
989 case LINESTYLETYPE:
990 r = "linestyle";
991 break;
992 case FONTTYPE:
993 r = "font";
994 break;
995 case PICTURETYPE:
996 r = "picture";
997 break;
998 case STROKEPATHTYPE:
999 r = "path (from StrokePath)";
1000 break;
1001 default:
1002 r = "UNKNOWN";
1003 break;
1004 }
1005 }
1006 return(r);
1007 }
1008 /*
1009 :h4.ObjectPostMortem() - Prints as Much as We Can About a Bad Object
1010
1011 This is a subroutine of TypeErr() and ArgErr().
1012 */
1013
1014 /*ARGSUSED*/
ObjectPostMortem(obj)1015 static ObjectPostMortem(obj) /* non-ANSI avoids overly strict type checking */
1016 register struct xobject *obj;
1017 {
1018 extern struct XYspace *USER;
1019
1020 Pragmatics("Debug", 10);
1021 IfTrace2(TRUE,"Bad object is of %s type %z\n", TypeFmt(obj->type), obj);
1022
1023 IfTrace0((obj == (struct xobject *) USER),
1024 "Suspect that InitImager() was omitted.\n");
1025 Pragmatics("Debug", 0);
1026 }
1027
1028 /*
1029 :h3.ArgErr() - Invalid Argument Passed to a Routine
1030
1031 A common routine to report argument errors. It is usually called
1032 is returned to the caller in case MustCrash is FALSE and ArgErr
1033 returns to its caller.
1034 */
1035
ArgErr(string,obj,ret)1036 struct xobject *ArgErr(string, obj, ret) /* non-ANSI avoids overly strict type checking */
1037 char *string; /* description of error */
1038 struct xobject *obj; /* object, if any, that was in error */
1039 struct xobject *ret; /* object returned to caller or NULL */
1040 {
1041 if (MustCrash)
1042 LineIOTrace = TRUE;
1043 IfTrace1(TRUE,"ARGUMENT ERROR-- %s.\n", string);
1044 if (obj != NULL)
1045 ObjectPostMortem(obj);
1046 if (MustCrash)
1047 abort("Terminating because of CrashOnUserError...");
1048 else
1049 ErrorMessage = string;
1050 return(ret);
1051 }
1052
1053 /*
1054 :h3.abort() - Crash Due to Error
1055
1056 Defined in objects.h to be FatalError(), the server's abort routine.
1057 */
1058
1059 /*
1060 :h3.REAL Miscellaneous Stuff
1061
1062 :h4.ErrorMsg() - Return the User an Error Message
1063 */
1064
ErrorMsg()1065 char *ErrorMsg()
1066 {
1067 register char *r;
1068
1069 r = ErrorMessage;
1070 ErrorMessage = NULL;
1071 return(r);
1072 }
1073
1074 /*
1075 :h4.InitImager() - Initialize TYPE1IMAGER
1076
1077 We check that a short is 16 bits and a long 32 bits; we have made
1078 those assumptions elsewhere in the code. (This is almost a C standard,
1079 anyway.) Note that TYPE1IMAGER makes no assumptions about the size of an
1080 'int'!
1081 :i1/portability assumptions/
1082 */
1083
InitImager()1084 void InitImager()
1085 {
1086
1087 /* Check to see if we have been using our own malloc. If so,*/
1088 /* Undef malloc so that we can get to the system call. */
1089 /* All other calls to malloc are defined to xiMalloc. */
1090
1091
1092 /* if (sizeof(short) != 2 || sizeof(INT32) != 4)
1093 abort("Fundamental TYPE1IMAGER assumptions invalid in this port");
1094 */
1095 InitSpaces();
1096 InitFonts();
1097 InitFiles();
1098 /*
1099 In some environments, constants and/or exception handling need to be
1100 */
1101 LibInit();
1102 }
1103 /*
1104 :h4.TermImager() - Terminate TYPE1IMAGER
1105
1106 This only makes sense in a server environment; true TYPE1IMAGER needs do
1107 nothing.
1108 */
TermImager()1109 void TermImager()
1110 {
1111 return;
1112 }
1113 /*
1114 :h4.reportusage() - A Stub to Get a Clean Link with Portable PMP
1115 */
reportusage()1116 void reportusage()
1117 {
1118 return;
1119 }
1120