| 1 | .\" $Id: TIFFSetField.3tiff,v 1.4 2006/01/02 23:50:44 bfriesen Exp $ |
| 2 | .\" |
| 3 | .\" Copyright (c) 1988-1997 Sam Leffler |
| 4 | .\" Copyright (c) 1991-1997 Silicon Graphics, Inc. |
| 5 | .\" |
| 6 | .\" Permission to use, copy, modify, distribute, and sell this software and |
| 7 | .\" its documentation for any purpose is hereby granted without fee, provided |
| 8 | .\" that (i) the above copyright notices and this permission notice appear in |
| 9 | .\" all copies of the software and related documentation, and (ii) the names of |
| 10 | .\" Sam Leffler and Silicon Graphics may not be used in any advertising or |
| 11 | .\" publicity relating to the software without the specific, prior written |
| 12 | .\" permission of Sam Leffler and Silicon Graphics. |
| 13 | .\" |
| 14 | .\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, |
| 15 | .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY |
| 16 | .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. |
| 17 | .\" |
| 18 | .\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR |
| 19 | .\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, |
| 20 | .\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, |
| 21 | .\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF |
| 22 | .\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE |
| 23 | .\" OF THIS SOFTWARE. |
| 24 | .\" |
| 25 | .if n .po 0 |
| 26 | .TH TIFFSetField 3TIFF "October 29, 2004" "libtiff" |
| 27 | .SH NAME |
| 28 | TIFFSetField, TIFFVSetField \- set the value(s) of a tag in a |
| 29 | .SM TIFF |
| 30 | file open for writing |
| 31 | .SH SYNOPSIS |
| 32 | .B "#include <tiffio.h>" |
| 33 | .sp |
| 34 | .BI "int TIFFSetField(TIFF *" tif ", ttag_t " tag ", " ... ")" |
| 35 | .sp |
| 36 | .B "#include <stdarg.h>" |
| 37 | .sp |
| 38 | .BI "int TIFFVSetField(TIFF *" tif ", ttag_t " tag ", va_list " ap ")" |
| 39 | .SH DESCRIPTION |
| 40 | .IR TIFFSetField |
| 41 | sets the value of a field |
| 42 | or pseudo-tag in the current directory associated with |
| 43 | the open |
| 44 | .SM TIFF |
| 45 | file |
| 46 | .IR tif . |
| 47 | (A |
| 48 | .I pseudo-tag |
| 49 | is a parameter that is used to control the operation of the |
| 50 | .SM TIFF |
| 51 | library but whose value is not read or written to the underlying file.) |
| 52 | To set the value of a field |
| 53 | the file must have been previously opened for writing with |
| 54 | .IR TIFFOpen (3TIFF); |
| 55 | pseudo-tags can be set whether the file was opened for reading |
| 56 | or writing. |
| 57 | The field is identified by |
| 58 | .IR tag , |
| 59 | one of the values defined in the include file |
| 60 | .B tiff.h |
| 61 | (see also the table below). |
| 62 | The actual value is specified using a variable argument list, |
| 63 | as prescribed by the |
| 64 | .IR stdarg (3) |
| 65 | interface (\c |
| 66 | or, on some machines, the |
| 67 | .IR varargs (3) |
| 68 | interface.) |
| 69 | .PP |
| 70 | .IR TIFFVSetField |
| 71 | is functionally equivalent to |
| 72 | .IR TIFFSetField |
| 73 | except that it takes a pointer to a variable |
| 74 | argument list. |
| 75 | .I TIFFVSetField |
| 76 | is useful for writing routines that are layered |
| 77 | on top of the functionality provided by |
| 78 | .IR TIFFSetField . |
| 79 | .PP |
| 80 | The tags understood by |
| 81 | .IR libtiff , |
| 82 | the number of parameter values, and the |
| 83 | expected types for the parameter values are shown below. |
| 84 | The data types are: |
| 85 | .I char* |
| 86 | is null-terminated string and corresponds to the |
| 87 | .SM ASCII |
| 88 | data type; |
| 89 | .I uint16 |
| 90 | is an unsigned 16-bit value; |
| 91 | .I uint32 |
| 92 | is an unsigned 32-bit value; |
| 93 | .I uint16* |
| 94 | is an array of unsigned 16-bit values. |
| 95 | .I void* |
| 96 | is an array of data values of unspecified type. |
| 97 | |
| 98 | Consult the |
| 99 | .SM TIFF |
| 100 | specification for information on the meaning of each tag. |
| 101 | .PP |
| 102 | .nf |
| 103 | .ta \w'TIFFTAG_CONSECUTIVEBADFAXLINES'u+2n +\w'Count'u+2n +\w'TIFFFaxFillFunc \(dg'u+2n |
| 104 | \fITag Name\fP \fICount\fP \fITypes\fP \fINotes\fP |
| 105 | .sp 5p |
| 106 | TIFFTAG_ARTIST 1 char* |
| 107 | TIFFTAG_BADFAXLINES 1 uint32 |
| 108 | TIFFTAG_BITSPERSAMPLE 1 uint16 \(dg |
| 109 | TIFFTAG_CLEANFAXDATA 1 uint16 |
| 110 | TIFFTAG_COLORMAP 3 uint16* 1<<BitsPerSample arrays |
| 111 | TIFFTAG_COMPRESSION 1 uint16 \(dg |
| 112 | TIFFTAG_CONSECUTIVEBADFAXLINES 1 uint32 |
| 113 | TIFFTAG_COPYRIGHT 1 char* |
| 114 | TIFFTAG_DATETIME 1 char* |
| 115 | TIFFTAG_DOCUMENTNAME 1 char* |
| 116 | TIFFTAG_DOTRANGE 2 uint16 |
| 117 | TIFFTAG_EXTRASAMPLES 2 uint16,uint16* \(dg count & types array |
| 118 | TIFFTAG_FAXFILLFUNC 1 TIFFFaxFillFunc G3/G4 compression pseudo-tag |
| 119 | TIFFTAG_FAXMODE 1 int \(dg G3/G4 compression pseudo-tag |
| 120 | TIFFTAG_FILLORDER 1 uint16 \(dg |
| 121 | TIFFTAG_GROUP3OPTIONS 1 uint32 \(dg |
| 122 | TIFFTAG_GROUP4OPTIONS 1 uint32 \(dg |
| 123 | TIFFTAG_HALFTONEHINTS 2 uint16 |
| 124 | TIFFTAG_HOSTCOMPUTER 1 char* |
| 125 | TIFFTAG_ICCPROFILE 2 uint32,void* count, profile data |
| 126 | TIFFTAG_IMAGEDEPTH 1 uint32 \(dg |
| 127 | TIFFTAG_IMAGEDESCRIPTION 1 char* |
| 128 | TIFFTAG_IMAGELENGTH 1 uint32 |
| 129 | TIFFTAG_IMAGEWIDTH 1 uint32 \(dg |
| 130 | TIFFTAG_INKNAMES 2 uint16, char* |
| 131 | TIFFTAG_INKSET 1 uint16 \(dg |
| 132 | TIFFTAG_JPEGCOLORMODE 1 int \(dg JPEG pseudo-tag |
| 133 | TIFFTAG_JPEGQUALITY 1 int JPEG pseudo-tag |
| 134 | TIFFTAG_JPEGTABLES 2 uint32*,void* \(dg count & tables |
| 135 | TIFFTAG_JPEGTABLESMODE 1 int \(dg JPEG pseudo-tag |
| 136 | TIFFTAG_MAKE 1 char* |
| 137 | TIFFTAG_MATTEING 1 uint16 \(dg |
| 138 | TIFFTAG_MAXSAMPLEVALUE 1 uint16 |
| 139 | TIFFTAG_MINSAMPLEVALUE 1 uint16 |
| 140 | TIFFTAG_MODEL 1 char* |
| 141 | TIFFTAG_ORIENTATION 1 uint16 |
| 142 | TIFFTAG_PAGENAME 1 char* |
| 143 | TIFFTAG_PAGENUMBER 2 uint16 |
| 144 | TIFFTAG_PHOTOMETRIC 1 uint16 |
| 145 | TIFFTAG_PHOTOSHOP ? uint32,void* count, data |
| 146 | TIFFTAG_PLANARCONFIG 1 uint16 \(dg |
| 147 | TIFFTAG_PREDICTOR 1 uint16 \(dg |
| 148 | TIFFTAG_PRIMARYCHROMATICITIES 1 float* 6-entry array |
| 149 | TIFFTAG_REFERENCEBLACKWHITE 1 float* \(dg 2*SamplesPerPixel array |
| 150 | TIFFTAG_RESOLUTIONUNIT 1 uint16 |
| 151 | TIFFTAG_RICHTIFFIPTC 2 uint32,void* count, data |
| 152 | TIFFTAG_ROWSPERSTRIP 1 uint32 \(dg must be > 0 |
| 153 | TIFFTAG_SAMPLEFORMAT 1 uint16 \(dg |
| 154 | TIFFTAG_SAMPLESPERPIXEL 1 uint16 \(dg value must be <= 4 |
| 155 | TIFFTAG_SMAXSAMPLEVALUE 1 double |
| 156 | TIFFTAG_SMINSAMPLEVALUE 1 double |
| 157 | TIFFTAG_SOFTWARE 1 char* |
| 158 | TIFFTAG_STONITS 1 double \(dg |
| 159 | TIFFTAG_SUBFILETYPE 1 uint32 |
| 160 | TIFFTAG_SUBIFD 2 uint16,uint32* count & offsets array |
| 161 | TIFFTAG_TARGETPRINTER 1 char* |
| 162 | TIFFTAG_THRESHHOLDING 1 uint16 |
| 163 | TIFFTAG_TILEDEPTH 1 uint32 \(dg |
| 164 | TIFFTAG_TILELENGTH 1 uint32 \(dg must be a multiple of 8 |
| 165 | TIFFTAG_TILEWIDTH 1 uint32 \(dg must be a multiple of 8 |
| 166 | TIFFTAG_TRANSFERFUNCTION 1 or 3\(dd uint16* 1<<BitsPerSample entry arrays |
| 167 | TIFFTAG_WHITEPOINT 1 float* 2-entry array |
| 168 | TIFFTAG_XMLPACKET 2 uint32,void* count, data |
| 169 | TIFFTAG_XPOSITION 1 float |
| 170 | TIFFTAG_XRESOLUTION 1 float |
| 171 | TIFFTAG_YCBCRCOEFFICIENTS 1 float* \(dg 3-entry array |
| 172 | TIFFTAG_YCBCRPOSITIONING 1 uint16 \(dg |
| 173 | TIFFTAG_YCBCRSAMPLING 2 uint16 \(dg |
| 174 | TIFFTAG_YPOSITION 1 float |
| 175 | TIFFTAG_YRESOLUTION 1 float |
| 176 | .fi |
| 177 | .sp 5p |
| 178 | \(dg Tag may not have its values changed once data is written. |
| 179 | .br |
| 180 | .fi |
| 181 | \(dd |
| 182 | If |
| 183 | .I SamplesPerPixel |
| 184 | is one, then a single array is passed; otherwise three arrays should be |
| 185 | passed. |
| 186 | .fi |
| 187 | * The contents of this field are quite complex. See |
| 188 | .BR "The ICC Profile Format Specification" , |
| 189 | Annex B.3 "Embedding ICC Profiles in TIFF Files" |
| 190 | (available at http://www.color.org) for an explanation. |
| 191 | .br |
| 192 | .SH "RETURN VALUES" |
| 193 | 1 is returned if the operation was successful. |
| 194 | Otherwise, 0 is returned if an error was detected. |
| 195 | .SH DIAGNOSTICS |
| 196 | All error messages are directed to the |
| 197 | .BR TIFFError (3TIFF) |
| 198 | routine. |
| 199 | .PP |
| 200 | \fB%s: Cannot modify tag "%s" while writing\fP. |
| 201 | Data has already been written to the file, so the |
| 202 | specified tag's value can not be changed. |
| 203 | This restriction is applied to all tags that affect |
| 204 | the format of written data. |
| 205 | .PP |
| 206 | \fB%d: Bad value for "%s"\fP. |
| 207 | An invalid value was supplied for the named tag. |
| 208 | .SH "SEE ALSO" |
| 209 | .BR TIFFOpen (3TIFF), |
| 210 | .BR TIFFGetField (3TIFF), |
| 211 | .BR TIFFSetDirectory (3TIFF), |
| 212 | .BR TIFFWriteDirectory (3TIFF), |
| 213 | .BR TIFFReadDirectory (3TIFF), |
| 214 | .BR libtiff (3TIFF) |
| 215 | .PP |
| 216 | Libtiff library home page: |
| 217 | .BR http://www.remotesensing.org/libtiff/ |