KWWidgets
vtkKWResourceUtilities.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWResourceUtilities.h,v $
4 
5  Copyright (c) Kitware, Inc.
6  All rights reserved.
7  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
8 
9  This software is distributed WITHOUT ANY WARRANTY; without even
10  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
11  PURPOSE. See the above copyright notice for more information.
12 
13 =========================================================================*/
14 // .NAME vtkKWResourceUtilities - class that supports resource functions
15 // .SECTION Description
16 // vtkKWResourceUtilities provides methods to perform common resources
17 // operations.
18 
19 #ifndef __vtkKWResourceUtilities_h
20 #define __vtkKWResourceUtilities_h
21 
22 #include "vtkObject.h"
23 #include "vtkKWWidgets.h" // Needed for export symbols directives
24 
25 class vtkKWWidget;
26 
27 class KWWidgets_EXPORT vtkKWResourceUtilities : public vtkObject
28 {
29 public:
30  static vtkKWResourceUtilities* New();
31  vtkTypeRevisionMacro(vtkKWResourceUtilities,vtkObject);
32  void PrintSelf(ostream& os, vtkIndent indent);
33 
34  // Description:
35  // Read an image given its 'filename'.
36  // On success, modifies 'width', 'height', 'pixel_size' and 'pixels'
37  // accordingly. Note that 'pixels' is allocated automatically using the
38  // 'new' operator (i.e. it is up to the caller to free the memory using
39  // the 'delete' operator).
40  // The following formats are recognized (given the file extension):
41  // - PNG (.png)
42  // Return 1 on success, 0 otherwise.
43  static int ReadImage(const char *filename,
44  int *width, int *height,
45  int *pixel_size,
46  unsigned char **pixels);
47 
48  // Description:
49  // Read a PNG file given its 'filename'.
50  // On success, modifies 'width', 'height', 'pixel_size' and 'pixels'
51  // accordingly. Note that 'pixels' is allocated automatically using the
52  // 'new' operator (i.e. it is up to the caller to free the memory using
53  // the 'delete' operator).
54  // Note that grayscale images are promoted to RGB. Transparent images are
55  // promoted to RGBA. The bit depth is promoted (or shrunk) to 8 bits
56  // per component. The resulting 'pixel_size' is therefore always
57  // 3 (RGB) or 4 (RGBA).
58  // Return 1 on success, 0 otherwise.
59  static int ReadPNGImage(const char *filename,
60  int *width, int *height,
61  int *pixel_size,
62  unsigned char **pixels);
63 
64  // Description:
65  // Write a PNG file given its 'filename'.
66  // The bit depth has to be 8 bit (i.e. unsigned char).
67  // The 'pixel_size' can be 1 (grayscale), 2 (grayscale + alpha), 3 (RGB),
68  // or 4 (RGB + alpha).
69  // Return 1 on success, 0 otherwise.
70  static int WritePNGImage(const char *filename,
71  int width, int height,
72  int pixel_size,
73  const unsigned char *pixels);
74 
75  // Description:
76  // Convert 'nb_files' files (stored in an array of filenames given by
77  // 'filenames') into a C/C++ header given by 'header_filename'.
78  // The structure (if any) and contents of each file are decoded and
79  // written into a form that can be used programatically.
80  // An attempt is made to read the file as an image first (using ReadImage).
81  // If it succeeds, the width, height and pixel_size are stored in the
82  // header file as well as the buffer length and contents, prefixed with
83  // 'image_' and the name of the file *without* its extension.
84  // For example, the file foobar.png is converted into:
85  // static const unsigned int image_foobar_width = 19;
86  // static const unsigned int image_foobar_height = 19;
87  // static const unsigned int image_foobar_pixel_size = 3;
88  // static const unsigned long image_foobar_length = 40;
89  // static const unsigned long image_foobar_decoded_length = 1083;
90  // static const unsigned char image_foobar[] =
91  // "eNpjYCAfPH1wg1Q0qnFU46jGwaaRPAAAa7/zXA==";
92  // If the file can not be read as an image, it is treated as a simple
93  // stream of bytes and still converted accordingly. Only the buffer length
94  // and contents are output, prefixed with 'file_' and the name of the
95  // file *with* its extension ('.' are replaced by '_').
96  // For example, the file foobar.tcl is converted into:
97  // static const unsigned long file_foobar_tcl_length = 40
98  // static const unsigned long file_foobar_tcl_decoded_length = 2048
99  // static const unsigned char file_foobar_tcl[] =
100  // "eNpjYCAfPH1wg1Q0qnFU46jGwaaRPAAAa7/zXA==";
101  // Several options can be combined into the 'options' parameter.
102  // CONVERT_IMAGE_TO_HEADER_OPTION_ZLIB:
103  // => Compress the data using zlib
104  // CONVERT_IMAGE_TO_HEADER_OPTION_BASE64:
105  // => Encode the data in base64
106  // CONVERT_IMAGE_TO_HEADER_OPTION_UPDATE:
107  // => Update the header file only if one of the file(s) is/are newer
108  // Note that if the contents of the file is encoded using zlib and/or base64
109  // the _length field still represents the size of the *encoded*
110  // buffer. The expected size of the decoded buffer can be found using
111  // the _decoded_length field (which should match
112  // width * height * pixel_size for images)
113  // If ConvertImageToHeaderOptionAppend is specified, the header file
114  // is not overwritten, but contents is appened to it.
115  // If ConvertImageToHeaderOptionUsePathInName is specified, the full path
116  // to the file is used to generate the var name in the header.
117  //BTX
118  enum
119  {
120  ConvertImageToHeaderOptionZlib = 1,
121  ConvertImageToHeaderOptionBase64 = 2,
122  ConvertImageToHeaderOptionUpdate = 4,
123  ConvertImageToHeaderOptionAppend = 8,
124  ConvertImageToHeaderOptionUsePathInName = 16
125  };
126  //ETX
127  static int ConvertImageToHeader(
128  const char *header_filename,
129  const char **filenames,
130  int nb_files,
131  int options = 0,
132  const char *var_prefix = NULL);
133 
134  // Description:
135  // Encode a buffer that using zlib and/or base64.
136  // output_buffer is automatically allocated using the 'new' operator
137  // and should be deallocated using 'delete []'.
138  // The 'options' parameter is the same as ConvertImageToHeader.
139  // Return 1 on success, 0 otherwise (also sets *output to NULL on error).
140  static int EncodeBuffer(
141  const unsigned char *input, unsigned long input_length,
142  unsigned char **output, unsigned long *output_length,
143  int options);
144 
145  // Description:
146  // Decode a buffer that was encoded using zlib and/or base64.
147  // output_buffer is automatically allocated using the 'new' operator
148  // and should be deallocated using 'delete []'.
149  // Note that it does allocate an extra-byte (i.e. output_expected_length + 1)
150  // for convenience purposes, so that the resulting buffer can be
151  // NULL terminated manually.
152  // Return 1 on success, 0 otherwise (also sets *output to NULL on error).
153  static int DecodeBuffer(
154  const unsigned char *input, unsigned long input_length,
155  unsigned char **output, unsigned long output_expected_length);
156 
157 protected:
160 
161 private:
162  vtkKWResourceUtilities(const vtkKWResourceUtilities&); // Not implemented
163  void operator=(const vtkKWResourceUtilities&); // Not implemented
164 };
165 
166 #endif
167