KWWidgets
vtkKWResourceUtilities.h
Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003   Module:    $RCSfile: vtkKWResourceUtilities.h,v $
00004 
00005   Copyright (c) Kitware, Inc.
00006   All rights reserved.
00007   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
00008 
00009      This software is distributed WITHOUT ANY WARRANTY; without even
00010      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
00011      PURPOSE.  See the above copyright notice for more information.
00012 
00013 =========================================================================*/
00014 // .NAME vtkKWResourceUtilities - class that supports resource functions
00015 // .SECTION Description
00016 // vtkKWResourceUtilities provides methods to perform common resources
00017 //  operations.
00018 
00019 #ifndef __vtkKWResourceUtilities_h
00020 #define __vtkKWResourceUtilities_h
00021 
00022 #include "vtkObject.h"
00023 #include "vtkKWWidgets.h" // Needed for export symbols directives
00024 
00025 class vtkKWWidget;
00026 
00027 class KWWidgets_EXPORT vtkKWResourceUtilities : public vtkObject
00028 {
00029 public:
00030   static vtkKWResourceUtilities* New();
00031   vtkTypeRevisionMacro(vtkKWResourceUtilities,vtkObject);
00032   void PrintSelf(ostream& os, vtkIndent indent);
00033 
00034   // Description:
00035   // Read an image given its 'filename'.
00036   // On success, modifies 'width', 'height', 'pixel_size' and 'pixels' 
00037   // accordingly. Note that 'pixels' is allocated automatically using the
00038   // 'new' operator (i.e. it is up to the caller to free the memory using
00039   // the 'delete' operator).
00040   // The following formats are recognized (given the file extension):
00041   // - PNG (.png)
00042   // Return 1 on success, 0 otherwise.
00043   static int ReadImage(const char *filename,
00044                        int *width, int *height, 
00045                        int *pixel_size,
00046                        unsigned char **pixels);
00047 
00048   // Description:
00049   // Read a PNG file given its 'filename'.
00050   // On success, modifies 'width', 'height', 'pixel_size' and 'pixels' 
00051   // accordingly. Note that 'pixels' is allocated automatically using the
00052   // 'new' operator (i.e. it is up to the caller to free the memory using
00053   // the 'delete' operator).
00054   // Note that grayscale images are promoted to RGB. Transparent images are
00055   // promoted to RGBA. The bit depth is promoted (or shrunk) to 8 bits
00056   // per component. The resulting 'pixel_size' is therefore always
00057   // 3 (RGB) or 4 (RGBA).
00058   // Return 1 on success, 0 otherwise.
00059   static int ReadPNGImage(const char *filename,
00060                           int *width, int *height, 
00061                           int *pixel_size,
00062                           unsigned char **pixels);
00063 
00064   // Description:
00065   // Write a PNG file given its 'filename'.
00066   // The bit depth has to be 8 bit (i.e. unsigned char).
00067   // The 'pixel_size' can be 1 (grayscale), 2 (grayscale + alpha), 3 (RGB),
00068   // or 4 (RGB + alpha).
00069   // Return 1 on success, 0 otherwise.
00070   static int WritePNGImage(const char *filename,
00071                            int width, int height, 
00072                            int pixel_size,
00073                            const unsigned char *pixels);
00074 
00075   // Description:
00076   // Convert 'nb_files' files (stored in an array of filenames given by 
00077   // 'filenames') into a C/C++ header given by 'header_filename'.
00078   // The structure (if any) and contents of each file are decoded and 
00079   // written into a form that can be used programatically. 
00080   // An attempt is made to read the file as an image first (using ReadImage).
00081   // If it succeeds, the width, height and pixel_size are stored in the
00082   // header file as well as the buffer length and contents, prefixed with
00083   // 'image_' and the name of the file *without* its extension.
00084   // For example, the file foobar.png is converted into:
00085   //   static const unsigned int  image_foobar_width          = 19;
00086   //   static const unsigned int  image_foobar_height         = 19;
00087   //   static const unsigned int  image_foobar_pixel_size     = 3;
00088   //   static const unsigned long image_foobar_length         = 40;
00089   //   static const unsigned long image_foobar_decoded_length = 1083;
00090   //   static const unsigned char image_foobar[] = 
00091   //     "eNpjYCAfPH1wg1Q0qnFU46jGwaaRPAAAa7/zXA==";
00092   // If the file can not be read as an image, it is treated as a simple
00093   // stream of bytes and still converted accordingly. Only the buffer length
00094   // and contents are output, prefixed with 'file_' and the name of the
00095   // file *with* its extension ('.' are replaced by '_').
00096   // For example, the file foobar.tcl is converted into:
00097   //   static const unsigned long file_foobar_tcl_length         = 40
00098   //   static const unsigned long file_foobar_tcl_decoded_length = 2048
00099   //   static const unsigned char file_foobar_tcl[] = 
00100   //     "eNpjYCAfPH1wg1Q0qnFU46jGwaaRPAAAa7/zXA==";
00101   // Several options can be combined into the 'options' parameter.
00102   //   CONVERT_IMAGE_TO_HEADER_OPTION_ZLIB: 
00103   //    => Compress the data using zlib
00104   //   CONVERT_IMAGE_TO_HEADER_OPTION_BASE64: 
00105   //    => Encode the data in base64
00106   //   CONVERT_IMAGE_TO_HEADER_OPTION_UPDATE: 
00107   //    => Update the header file only if one of the file(s) is/are newer
00108   // Note that if the contents of the file is encoded using zlib and/or base64
00109   // the _length field still represents the size of the *encoded* 
00110   // buffer. The expected size of the decoded buffer can be found using
00111   // the _decoded_length field (which should match
00112   // width * height * pixel_size for images)
00113   // If ConvertImageToHeaderOptionAppend is specified, the header file
00114   // is not overwritten, but contents is appened to it.
00115   // If ConvertImageToHeaderOptionUsePathInName is specified, the full path
00116   // to the file is used to generate the var name in the header.
00117   //BTX
00118   enum
00119   {
00120     ConvertImageToHeaderOptionZlib   = 1,
00121     ConvertImageToHeaderOptionBase64 = 2,
00122     ConvertImageToHeaderOptionUpdate = 4,
00123     ConvertImageToHeaderOptionAppend = 8,
00124     ConvertImageToHeaderOptionUsePathInName = 16
00125   };
00126   //ETX
00127   static int ConvertImageToHeader(
00128     const char *header_filename,
00129     const char **filenames,
00130     int nb_files,
00131     int options = 0,
00132     const char *var_prefix = NULL);
00133 
00134   // Description:
00135   // Encode a buffer that using zlib and/or base64.
00136   // output_buffer is automatically allocated using the 'new' operator
00137   // and should be deallocated using 'delete []'.
00138   // The 'options' parameter is the same as ConvertImageToHeader.
00139   // Return 1 on success, 0 otherwise (also sets *output to NULL on error).
00140   static int EncodeBuffer(
00141     const unsigned char *input, unsigned long input_length, 
00142     unsigned char **output, unsigned long *output_length,
00143     int options);
00144 
00145   // Description:
00146   // Decode a buffer that was encoded using zlib and/or base64.
00147   // output_buffer is automatically allocated using the 'new' operator
00148   // and should be deallocated using 'delete []'.
00149   // Note that it does allocate an extra-byte (i.e. output_expected_length + 1)
00150   // for convenience purposes, so that the resulting buffer can be
00151   // NULL terminated manually.
00152   // Return 1 on success, 0 otherwise (also sets *output to NULL on error).
00153   static int DecodeBuffer(
00154     const unsigned char *input, unsigned long input_length, 
00155     unsigned char **output, unsigned long output_expected_length);
00156 
00157 protected:
00158   vtkKWResourceUtilities() {};
00159   ~vtkKWResourceUtilities() {};
00160 
00161 private:
00162   vtkKWResourceUtilities(const vtkKWResourceUtilities&); // Not implemented
00163   void operator=(const vtkKWResourceUtilities&); // Not implemented
00164 };
00165 
00166 #endif
00167