home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / STReadImageHeader.z / STReadImageHeader
Encoding:
Text File  |  2002-10-03  |  8.3 KB  |  199 lines
  1.  
  2.  
  3.  
  4. SSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))             IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo              SSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      STReadImageHeader, STWriteImageHeader - read/write STIFF image header
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddiiiioooo....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttiiiiffffffff....hhhh>>>>
  14.  
  15.      iiiinnnntttt SSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((SSSSTTTTSSSSttttrrrreeeeaaaammmm ****sssstttt,,,, SSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr ****hhhhdddd))));;;;
  16.  
  17.      iiiinnnntttt SSSSTTTTWWWWrrrriiiitttteeeeIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((SSSSTTTTSSSSttttrrrreeeeaaaammmm ****sssstttt,,,, SSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr ****hhhhdddd,,,,
  18.                             iiiinnnntttt llllaaaasssstttt))));;;;
  19.  
  20. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.      Before an image is read from a STIFF stream an image header must be
  22.      obtained from the stream. Similarly, before an image is written to a
  23.      STIFF stream an image header structure must be filled in and written to
  24.      the stream. The functions _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r and _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r assist
  25.      with these image header tasks.
  26.  
  27.      _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r reads the image header information from the stream
  28.      specified by _s_t and places the information in the image header structure
  29.      specified by _h_d. _s_t must point to a STIFF stream open for reading.
  30.      Following a successful call to _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r, the function _S_T_R_e_a_d can
  31.      be called to read the actual image data. The amount of image data
  32.      available can be found in the _S_T_I_m_a_g_e_H_e_a_d_e_r structure.  In addition,
  33.      following a successful call to _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r the TIFF tag list read
  34.      from the STIFF stream can be queried using the _S_T_G_e_t_T_a_g function.
  35.  
  36.      After the last image has been read from a STIFF stream, the next call to
  37.      _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r will return -1, and _S_T_e_r_r_n_o will be set to SSSSTTTTEEEEEEEEOOOOFFFF (see
  38.      below).
  39.  
  40.      _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r writes the image header to the STIFF stream specified
  41.      by _s_t. Before a call to _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r any caller specific TIFF tags
  42.      should be added to the output tag list using the _S_T_A_d_d_T_a_g function.
  43.  
  44.      Make sure that all fields of the SSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr structure passed to
  45.      _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r contain reasonable values; otherwise, garbage will be
  46.      written into the STIFF stream.
  47.  
  48.      Following a successful call to _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r the actual image data
  49.      can be written to the stream using _S_T_W_r_i_t_e. The amount of image data that
  50.      must be written to the stream is specified in the _S_T_I_m_a_g_e_H_e_a_d_e_r
  51.      structure. Note that following a successful call to _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r
  52.      the output TIFF tag list is cleared.
  53.  
  54.      The _l_a_s_t parameter to _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r should be set to 1 if this is to
  55.      be the last image written to this stream.  In this case,
  56.      _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r will store a value in the stream to indicate to
  57.      readers that this is the last image. _l_a_s_t should be set to 0 if more
  58.      images are to be written after this one, in which case _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r
  59.      calculates the offset of where the next image will start and stores that
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))             IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo              SSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))
  71.  
  72.  
  73.  
  74.      location in the stream.
  75.  
  76.      The _S_T_I_m_a_g_e_H_e_a_d_e_r structure is defined as follows.
  77.  
  78.           typedef struct tag_imghdr {
  79.               unsigned long width, height;    /* Dimensions in pixels */
  80.               unsigned short bitsPerSample;   /* Bits per channel */
  81.               unsigned short samplesPerPixel; /* # of color channels */
  82.               unsigned long imgbytes;         /* Bytes of image data */
  83.               STType type;                    /* Image data type */
  84.               STPlane plane;                  /* Planar configuration */
  85.           } STImageHeader;
  86.  
  87.  
  88. TTTTIIIIFFFFFFFF TTTTAAAAGGGGSSSS UUUUSSSSEEEEDDDD
  89.      The _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r function will write the TIFF tags listed below
  90.      into the STIFF stream. Caller specific tags would be output in addition
  91.      to the tags listed. The tags are expressed in terms of their names in the
  92.      header file _s_t_i_f_f._h
  93.  
  94.      STBitsPerSample
  95.      STImageLength
  96.      STImageWidth
  97.      STPhotometricInterpretation
  98.      STPlanarConfiguration
  99.      STSamplesPerPixel
  100.      STStripByteCounts
  101.      STStripOffsets
  102.  
  103. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  104.      Both _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r and _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r return 0 if execution was
  105.      successful. -1 is returned and _S_T_e_r_r_n_o is set if an execution error has
  106.      occurred.
  107.  
  108. EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS
  109.      _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r will fail under the following circumstances.
  110.  
  111.      STEBADTAG                Invalid TIFF tag.
  112.  
  113.      STENOMEM                 Out of memory.
  114.  
  115.      STEREADFROMWRITE         Attempt to read from a write stream.
  116.  
  117.      STESYSCALL               System call failed.
  118.  
  119.      STENEEDSEEK              Operation requires seeking on a stream.
  120.  
  121.      STEEOF                   End of stream.
  122.  
  123.      _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r will fail under the following circumstances.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))             IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo              SSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))
  137.  
  138.  
  139.  
  140.      STEBADTAG                Invalid TIFF tag.
  141.  
  142.      STENOMEM                 Out of memory.
  143.  
  144.      STEWRITETOREAD           Attempt to write to a read only stream.
  145.  
  146.      STESYSCALL               System call failed.
  147.  
  148.      STENEEDSEEK              Operation requires seeking on a stream.
  149.  
  150. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  151.      libstiff(3), STAddTag(3).
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.