objects.c

source code: Covert TXT to PDF

/* $XConsortium: objects.c,v 1.5 92/03/20 15:56:06 eswu Exp $ */
/* Copyright International Business Machines, Corp. 1991
 * All Rights Reserved
 * Copyright Lexmark International, Inc. 1991
 * All Rights Reserved
 *
 * License to use, copy, modify, and distribute this software and its
 * documentation for any purpose and without fee is hereby granted,
 * provided that the above copyright notice appear in all copies and that
 * both that copyright notice and this permission notice appear in
 * supporting documentation, and that the name of IBM or Lexmark not be
 * used in advertising or publicity pertaining to distribution of the
 * software without specific, written prior permission.
 *
 * IBM AND LEXMARK PROVIDE THIS SOFTWARE "AS IS", WITHOUT ANY WARRANTIES OF
 * ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO ANY
 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
 * AND NONINFRINGEMENT OF THIRD PARTY RIGHTS.  THE ENTIRE RISK AS TO THE
 * QUALITY AND PERFORMANCE OF THE SOFTWARE, INCLUDING ANY DUTY TO SUPPORT
 * OR MAINTAIN, BELONGS TO THE LICENSEE.  SHOULD ANY PORTION OF THE
 * SOFTWARE PROVE DEFECTIVE, THE LICENSEE (NOT IBM OR LEXMARK) ASSUMES THE
 * ENTIRE COST OF ALL SERVICING, REPAIR AND CORRECTION.  IN NO EVENT SHALL
 * IBM OR LEXMARK BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
 * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
 * THIS SOFTWARE.
 */
 /* OBJECTS  CWEB         V0025 ********                             */
/*
:h1.OBJECTS Module - TYPE1IMAGER Objects Common Routines
 
This module defines and implements the C structures that represent
objects in the TYPE1IMAGER.  All common routines for manipulating these
objects are defined in this module.  Specific routines for
specific objects are defined in the modules that deal with that
object type.
 
 
&author. Jeffrey B. Lotspiech ([e-mail])
 
 
:h3.Include Files
 
The included files are:
*/
#define   GLOBALS  1         /* see :hdref refid=debugvar.                   */
/*
The following two includes are C standards; we include them because we
use 'toupper' and the 'str'-type functions in this module.  Potentially
these may be defined as macros; if these ".h" files do not exist on your
system it is a pretty safe bet that these are external entry points and
you do do not need to include these header files.
*/


#include  "types.h"
#include  <stdio.h>
#include  <stdlib.h>
#include  <string.h>
#include  <ctype.h>
#include  <setjmp.h>

/*
override incorrect system functions; for example you might define
a macro for "strcpy" that diverts it to "my_strcpy".
*/
 
                               /* moved these includes from above the    */
                               /*   was included first (it contains com- */
                               /*   piler defines).  dsr 081291          */
#include  "objects.h"
#include  "spaces.h"
#include  "paths.h"
#include  "regions.h"
#include  "fonts.h"
#include  "pictures.h"
#include  "strokes.h"
#include  "cluts.h"
static char *TypeFmt();
static int ObjectPostMortem();

/*
:h3.The "pointer" Macro - Define a Generic Pointer
 
Sadly, many compilers will give a warning message when a pointer to
one structure is assigned to a pointer to another.  We've even seen
some that give severe errors (when the wrong pointer type is used as
an initializer or returned from a function).  TYPE1IMAGER has routines
like Dup and Allocate that are perfectly willing to duplicate or
allocate any of a number of different types of structures.  How to
declare them in a truely portable way?
 
Well, there is no single good answer that I've found.  You can always
beg the question and "cast" everything.  I find this distracting and the
resulting code ugly.  On the other hand, we have found at least one
compiler that will accept "void *" as a generic pointer that can
assigned to any other pointer type without error or warning (apparently
this is also the ANSI standard).  So, we define "void *" to be a generic
pointer.  (You might have to change this for your compiler; the "ifndef"
allows the change to be made on the command line if you want.)
:i1/portability assumptions/
*/
/*SHARED LINE(S) ORIGINATED HERE*/
/*
:h3.Functions Provided to the TYPE1IMAGER User
 
This module provides the following TYPE1IMAGER entry points:
*/
/*SHARED LINE(S) ORIGINATED HERE*/
/*
Note that entry points that are intended for use external to TYPE1IMAGER
begin with the characters :q/xi/.  Macros are used to make the names
more mnemonic.
*/
 
/*
:h3.Functions Provided to Other Modules
 
This module provides the following functions for other modules:
*/
/*SHARED LINE(S) ORIGINATED HERE*/
/*
Note that entry points that intended for use within TYPE1IMAGER, but
which must be global because they are used across module boundaries,
begin with the characters :q/I_/.  Macros are used to make the names
more mnemonic.
 
Entry points totally within a module use mnemonic names and are
declared :hp2/static/.  One of the compilers I used had a bug when
static functions were passed as addresses.  Thus, some functions
which are logically "static" are not so declared.
 
Note also the trick of declaring routines, like Consume(), with a
variable number of arguments.  To avoid the restrictions on variable
numbers of arguments in the macro processor, we just replace the
text 'Consume' with 'I_Consume'.
*/
/*
:h3.Macros Provided to Other Modules
 
This is the module where we define all the useful constants like
TRUE, FALSE, and NULL, and simple expressions like TYPE1_MIN(),
TYPE1_MAX(), and TYPE1_ABS().
We might as well get to it right here:
*/
/*SHARED LINE(S) ORIGINATED HERE*/
/*
Notice that upper case is used for constant values and macro
definitions.  I generally follow that convention.
 
Many more global macros are defined later in this module.
*/
/*
:h2.Basic TYPE1IMAGER Object Structure
 
All TYPE1IMAGER objects which are available to the user have a common
header.  This header is defined below:
*/
 
/*SHARED LINE(S) ORIGINATED HERE*/
/*
The following define is an attempt to centralize the definition of the
common xobject data shared by structures that are derived from the
generic xobject structure. For example, the structure font, defined in
fonts.shr :
&code.
    struct font {
           char type;
           char flag;
           int references;
           ... other data types & structs ...
           }
&ecode.
would now be defined as:
&code.
    struct font {
           XOBJ_COMMON
           ... other data types & structs ...
           }
&ecode.
Thus we have a better-structured inheritance mechanism. 3-26-91 PNM
*/
/*SHARED LINE(S) ORIGINATED HERE*/
/*
:h3.Object Type Definitions
 
These constants define the values which go in the 'type' field of
an TYPE1IMAGER object structure:
*/
/*SHARED LINE(S) ORIGINATED HERE*/
/*
:h3.Flag Byte Definitions
 
Many programmers define flag bits as a mask (for example, 0x04), and
test, set, and reset them as follows:
 
&code.
        if ((flag & PERMANENT) != 0)
 
        flag |= PERMANENT;
        flag &= &inv.PERMANENT;
:exmp.
 
I favor a style where the 'if' statement can ask a question:
 
&code.
        if (ISPERMANENT(flag))
 
        flag |= ISPERMANENT(ON);
        flag &= &inv.ISPERMANENT(ON);
 
:exmp.
This said, we now define two bit settings of the flag byte of the
object.  "ISPERMANENT" will be set by the user, when he calls
Permanent().  "ISIMMORTAL" will be used for compiled-in objects
that we don't want the user to ever destroy.
*/
/*SHARED LINE(S) ORIGINATED HERE*/
/*
Flag bit definitions that apply to all objects are assigned
starting with the least significant (0x01) bit.  Flag bit definitions
specific to a certain object type are assigned starting with the
most significant (0x80) bit.  We hope they never meet.
*/
/*
:h3 id=preserve.PRESERVE() Macro
 
Occasionally an TYPE1IMAGER operator is implemented by calling other
TYPE1IMAGER operators.  For example, Arc2() calls Conic().  When we
call more than one operator as a subroutine, we have to be careful
of temporary objects.  A temporary object will be consumed by the
subroutine operator and then is no longer available for the caller.
This can be prevented simply by bumping a temporary object's reference
count.
*/
/*SHARED LINE(S) ORIGINATED HERE*/
 
/*
:h3.RefRoll() Macro to Detect References Count Rollover
 
The following macro is designed to check for reference count rollover.
A return value of TRUE means rollover has not occurred; a return value
of FALSE means we cannot increment the reference count.  Note also that
those functions that use this macro must decrement the reference count
afterwards.  3-26-91 PNM
*/
 
#define RefRoll(obj)  (++(obj)->references > 0)
 
/*
:h2.TYPE1IMAGER Object Functions
 
:h3.LONGCOPY() - Macro to Copy "long" Aligned Data
 
Copying arbitrary bytes in C is a bit of a problem.  "strcpy" can't be
used, because 0 bytes are special-cased.  Most environments have a
routine "memcopy" or "bcopy" or "bytecopy" that copies memory containing
zero bytes.  Sadly, there is no standard on the name of such a routine,
which makes it impossible to write truely portable code to use it.
 
It turns out that TYPE1IMAGER, when it wants to copy data, frequently
knows that both the source and destination are aligned on "long"
boundaries.  This allows us to copy by using "long *" pointers.  This
is usually very efficient on almost all processors.  Frequently, it
is more efficient than using general-purpose assembly language routines.
So, we define a macro to do this in a portable way.  "dest" and "source"
must be long-aligned, and "bytes" must be a multiple of "sizeof(long)":
*/
/*SHARED LINE(S) ORIGINATED HERE*/
/*
:h3.Allocate() - Allocating a Memory Block
 
Allocate returns a pointer to memory object that is a copy of
the template passed (if any).  In addition, extra bytes may be
allocated contiguously with the object.  (This may be useful for
variable size objects such as edge lists.  See :hdref refid=regions..)
 
Allocate() always returns a non-immortal object, even if the template is
immortal.  Therefore a non-NULL template must have a "flag" byte.
 
If the template is NULL, then 'size' bytes are cleared to all NULLs.
 
If the template is non-NULL, a new object is allocated in memory.
It therefore seems logical that its reference count field should be
set to 1. So, a nun-NULL template must also have a "references" field.
PNM 3-26-91
*/


/* to pacify gcc we put the externals here ... */
extern struct XYspace *USER;
extern jmp_buf stck_state;


struct xobject *t1_Allocate(size, template, extra)  /* non-ANSI; type checking was too strict */
       register int size;    /* number of bytes to allocate & initialize     */
       register struct xobject *template;  /* example structure to allocate  */
       register int extra;   /* any extra uninitialized bytes needed contiguously */
{
 
       register struct xobject *r;
 
       /*
       * round up 'size' and 'extra' to be an integer number of 'long's:
       */
       size = (size + sizeof(LONG) - 1) & -sizeof(LONG);
       extra = (extra + sizeof(LONG) - 1) & -sizeof(LONG);
       if (size + extra <= 0)
               abort("Non-positive allocate?", 15);
       r = (struct xobject *) malloc(size + extra);
 
       while (r == NULL) {
               if (!GimeSpace()) {
                       IfTrace1(TRUE, "malloc attempted %d bytes.\n",
                                           size + extra);
                       abort("We have REALLY run out of memory", 16);
               }
               r = (struct xobject *) malloc(size + extra);
       }
 
       /*
       * copy the template into the new memory:
       */
       if (template != NULL) {
       /* Added references count decrement if template is not permanent.
          This is for the case where Allocate is called by a Dupxxxx
          function, which was in turn called by Unique(). (PNM)        */
               if (!ISPERMANENT(template->flag))
                   --template->references;
               LONGCOPY(r, template, size);
               r->flag &= ~(ISPERMANENT(ON) | ISIMMORTAL(ON));
       /* added reference field 3-2-6-91 PNM */
               r->references = 1;
       }
       else {
               register char **p1;
 
               for (p1=(char **)r; size > 0; size -= sizeof(char *))
                       *p1++ = NULL;
       }
 
       if (MemoryDebug > 1) {
               register int *L;
               L = (int *) r;
               IfTrace4(TRUE, "Allocating at %p: %x %x %x\n",
                                           L, L[-1], L[0], L[1]);
       }
       return(r);
}
 
/*
:h3.Free() - Frees an Allocated Object
 
This routine makes a sanity check to make sure the "type" field of the
standard object structure has not been cleared.  If the object is
not a standard structure, then the macro "NonObjectFree" is available
that does not perform this check.
 
In either case, the object must not be the NULL pointer.  This preserves
portability, as the C system Xfree() will not always accept NULL.
*/
 
void Free(obj)              /* non-ANSI to avoid overly strict type checking */
       register struct xobject *obj;  /* structure to free                   */
{
       if (obj->type == INVALIDTYPE)
               abort("Free of already freed object?", 17);
       obj->type = INVALIDTYPE;
 
       if (MemoryDebug > 1) {
               register int *L;
               L = (int *) obj;
               IfTrace4(TRUE,"Freeing at %p: %x %x %x\n", L, L[-1], L[0], L[1]);
       }
 
       free(obj);
}
 
/*
:h3.Permanent() - Makes an Object Permanent
 
Real simple--just set a flag.  Every routine that consumes its objects
(which is almost every user entry) must check this flag, and not consume
the object if it is set.
 
If a temporary object is made permanent, and there is more than one
reference to it, we must first Copy() it, then set the ISPERMANENT
flag. Note also that the reference count must be incremented when an
object is changed from temporary to permanent (see the ISUNIQUE macro).
 
Note that the purpose of this function is to convert an object into a
permanent object:
  If it was permanent to begin with, we do nothing;
  If it was temporary and unique, we set the PERMANENT flag and increment
the reference count;
  If it was temporary and nonunique, we must make a unique Copy(), set
the PERMANENT flag, and set the reference count to 2. We must also
decrement the original object's reference count, because what we have
done is to change one of the old temporary handles to a permanent one.
3-26-91 PNM
*/