Return to picfile.3 CVS log

Up to [Research Unix] / researchv10dc / man / adm / man3

Annotation of researchv10dc/man/adm/man3/picfile.3, revision 1.1

1.1     ! root        1: .TH PICFILE 3X
        !             2: .CT graphics files
        !             3: .SH NAME
        !             4: picopen_r, picopen_w, picread, picwrite, picclose, picputprop, picgetprop, picunpack, picpack, picerror \- picture file I/O
        !             5: .SH SYNOPSIS
        !             6: .nf
        !             7: .B #include <picfile.h>
        !             8: .PP
        !             9: .B PICFILE *picopen_r(name)
        !            10: .B char *name;
        !            11: .PP
        !            12: .B "PICFILE *picopen_w(name, type, x0, y0, w, h, chan, argv, cmap)
        !            13: .B "char *name, *type, *chan, *argv[], *cmap;
        !            14: .PP
        !            15: .B int picread(pf, buf)
        !            16: .B PICFILE *pf;
        !            17: .B char *buf;
        !            18: .PP
        !            19: .B int picwrite(pf, buf)
        !            20: .B PICFILE *pf;
        !            21: .B char *buf;
        !            22: .PP
        !            23: .B void picclose(pf)
        !            24: .B PICFILE *pf;
        !            25: .PP
        !            26: .B PICFILE *picputprop(pf, name, value)
        !            27: .B PICFILE *pf;
        !            28: .B char *name, *value;
        !            29: .PP
        !            30: .B char *picgetprop(pf, name)
        !            31: .B PICFILE *pf;
        !            32: .B char *name;
        !            33: .PP
        !            34: .B "void picunpack(pf, pix, fmt, arg ...)
        !            35: .B PICFILE *pf;
        !            36: .B char *pix, *fmt;
        !            37: .PP
        !            38: .B "void picpack(pf, pix, fmt, arg ...)
        !            39: .B PICFILE *pf;
        !            40: .B char *pix, *fmt;
        !            41: .PP
        !            42: .B "void picerror(string)
        !            43: .B char *string;
        !            44: .fi
        !            45: .SH DESCRIPTION
        !            46: These functions read and write raster images in
        !            47: .IR picfile (5)
        !            48: format.
        !            49: They are loaded by option
        !            50: .B -lpicfile
        !            51: of
        !            52: .IR ld (1).
        !            53: Open picture files are referred to by pointers of type
        !            54: .BR PICFILE* .
        !            55: .PP
        !            56: .I Picopen_r
        !            57: opens the named picfile for reading and returns a pointer
        !            58: to the open file.
        !            59: If
        !            60: .I name
        !            61: is
        !            62: .L
        !            63: "IN"\fR,
        !            64: standard input is used.
        !            65: .PP
        !            66: .I Picopen_w
        !            67: similarly creates the named image file for writing.
        !            68: The name
        !            69: .L
        !            70: "OUT"
        !            71: refers to standard output.
        !            72: .I Type
        !            73: is a
        !            74: .B TYPE
        !            75: attribute, as described in
        !            76: .IR picfile (5);
        !            77: .I x0
        !            78: and
        !            79: .I y0
        !            80: are the upper left coordinates of the
        !            81: .BR WINDOW 
        !            82: attribute;
        !            83: .I w
        !            84: and
        !            85: .I h
        !            86: are the image width and heigth in pixels.
        !            87: .I Chan
        !            88: is a string specifying the order of channels for the
        !            89: .B CHAN
        !            90: attribute; the length of this string becomes the value of
        !            91: .BR NCHAN .
        !            92: .I Argv,
        !            93: if nonzero, is
        !            94: conventionally the second argument of the main program;
        !            95: see
        !            96: .IR exec (2).
        !            97: It becomes a 
        !            98: .B COMMAND
        !            99: attribute recording the provenance of the file.
        !           100: .PP
        !           101: The special call
        !           102: .B picopen_w(name, PIC_SAMEARGS(pf))
        !           103: creates a file with the same attributes as an already open
        !           104: picfile.
        !           105: .B PIC_SAMEARGS
        !           106: mentions
        !           107: .I argv
        !           108: by name, hence the name must be visible at the point of call.
        !           109: .PP
        !           110: .I Picread
        !           111: and
        !           112: .I picwrite
        !           113: read or write a single row of pixels using the
        !           114: character array
        !           115: .I buf.
        !           116: The length of the row is determined from the file's
        !           117: .B WINDOW
        !           118: and
        !           119: .B NCHAN
        !           120: attributes.
        !           121: One-bit-per-pixel images (of type
        !           122: .B bitmap
        !           123: or
        !           124: .BR ccitt-g4 ,
        !           125: for example)
        !           126: are decoded to one byte per pixel, 0 for black, 255 for white, and
        !           127: are encoded as 1 for pixel values less than 128 and 0 otherwise.
        !           128: Files of type
        !           129: .B ccir601
        !           130: are decoded into conventional
        !           131: .B rgb
        !           132: channels.
        !           133: .PP
        !           134: .I Picclose
        !           135: closes a picfile and frees associated storage.
        !           136: .PP
        !           137: .I Picputprop
        !           138: called after 
        !           139: .I picopen_w
        !           140: but before
        !           141: .I picwrite
        !           142: adds header attributes, returning a (probably changed) value of the 
        !           143: .B PICFILE
        !           144: pointer.
        !           145: .PP
        !           146: .I Picgetprop
        !           147: returns a pointer to the value of the named attribute, or
        !           148: 0 if the picfile does not have the attribute.
        !           149: In both
        !           150: .I Picputprop
        !           151: and
        !           152: .I picgetprop,
        !           153: with multiple appearances (e.g.
        !           154: .BR COMMAND )
        !           155: are expressed as a sequence of
        !           156: values separated by newlines.
        !           157: .PP
        !           158: The header file defines macros to extract commonly-used
        !           159: attributes:
        !           160: .IP
        !           161: .EX
        !           162: PIC_NCHAN(pf), PIC_WIDTH(pf), PIC_HEIGHT(pf),
        !           163: PIC_SAMEARGS(pf) \fR(see \fP\&picopen_w\fR)\fP
        !           164: .EE
        !           165: .PP
        !           166: .I Picunpack
        !           167: extracts the channels of pixel array
        !           168: .I pix
        !           169: into separate array
        !           170: .I args
        !           171: of types described by the
        !           172: .I fmt
        !           173: character string.
        !           174: Format characters are
        !           175: .BR c ,
        !           176: .BR s ,
        !           177: .BR l ,
        !           178: .BR f ,
        !           179: .BR d ,
        !           180: for arrays of types unsigned char, short, long,
        !           181: float, and double.
        !           182: Format character
        !           183: .B _
        !           184: designates a picfile channel to be skipped.
        !           185: .I Picpack
        !           186: reverses the process.
        !           187: These routines effect a standard machine-independent byte
        !           188: ordering.
        !           189: .PP
        !           190: .IR Picerror
        !           191: prints messages for errors resulting from calls to
        !           192: .I picfile
        !           193: routines.
        !           194: .RI ( Perror (3)
        !           195: cannot describe some error conditions,
        !           196: like malformed header lines.)
        !           197: .SH EXAMPLES
        !           198: Unpack the green and z channels from a file with channels
        !           199: .B rgbz...
        !           200: .br
        !           201: .ns
        !           202: .IP
        !           203: .EX
        !           204: PICFILE *pf = picopen_r("file");
        !           205: extern char pixels[], green[][1000];
        !           206: extern float zdepth[][1000];
        !           207: for(i=0; picread(pf, pixels); i)
        !           208:        picunpack(pf, pixels, "_c_f", green[i], zdepth[i]);
        !           209: .EE
        !           210: .PP
        !           211: Reflect a picture about its vertical midline.
        !           212: .br
        !           213: .ns
        !           214: .IP
        !           215: .EX
        !           216: PICFILE *in = picopen_r("picture");
        !           217: PICFILE *out = picopen_w("OUT", PIC_SAMEARGS(in));
        !           218: int w = PIC_WIDTH(in);
        !           219: int n = PIC_NCHAN(in);
        !           220: char *buffer = malloc(w*n), *temp = malloc(n);
        !           221: while (picread(in, buffer)) {
        !           222:        char *left = buffer;
        !           223:        char *right = buffer + n*(w - 1);
        !           224:        for( ; left<right; left+=n, right-=n) {
        !           225:                strncpy(temp, left, n);
        !           226:                strncpy(left, right, n);
        !           227:                strncpy(right, temp, n);
        !           228:        }
        !           229:        picwrite(out, buffer);
        !           230: }
        !           231: .EE
        !           232: .SH SEE ALSO
        !           233: .IR picfile (5),
        !           234: .IR pico (1),
        !           235: .IR bcp (1)
        !           236: .SH DIAGNOSTICS
        !           237: .I Picread
        !           238: returns 1 on success, 0 on end of file or error.
        !           239: .br
        !           240: .I Picopen_r
        !           241: and
        !           242: .I picopen_w
        !           243: return 0 for unopenable files.
        !           244: .SH BUGS
        !           245: .I Picpack
        !           246: and
        !           247: .I picunpack
        !           248: store and retrieve floating point channels (types
        !           249: .B f
        !           250: and
        !           251: .BR d )
        !           252: using native floating-point, rather than something
        !           253: machine independent like IEEE format.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.