![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to picfile.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / man / man3|
Return to picfile.3 CVS log | Up to [Research Unix] / researchv10dc / man / man3 |
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.