summaryrefslogtreecommitdiff
path: root/legacy/eet/src/lib/Eet.h
blob: 57e231f89f90e5bfffe81648195fd680e0c28982 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
#ifndef _EET_H
#define _EET_H

/***************************************************************************/

/*
 * EET - E file chunk reading/writing library
 * 
 * What is it?
 * It is a tiny library designed to write an arbitary set of chunks of data
 * to a file and optionally compress each chunk (very much like a zip file)
 * and allow fast random-access reading of the file later on. It does not
 * do zip as zip itself has more complexity than we need, and it was much
 * simpler to impliment this once here.
 * 
 */

/***************************************************************************/

#ifdef __cplusplus
extern "C" {
#endif

/***************************************************************************/

#define EET_T_UNKNOW     0
#define EET_T_CHAR       1
#define EET_T_SHORT      2
#define EET_T_INT        3
#define EET_T_LONG_LONG  4
#define EET_T_FLOAT      5
#define EET_T_DOUBLE     6
#define EET_T_UCHAR      7
#define EET_T_USHORT     8
#define EET_T_UINT       9
#define EET_T_ULONG_LONG 10
#define EET_T_STRING     11
#define EET_T_LAST       12

#define EET_G_UNKNOWN    100
#define EET_G_ARRAY      101
#define EET_G_VAR_ARRAY  102
#define EET_G_LIST       103
#define EET_G_HASH       104
#define EET_G_LAST       105

/***************************************************************************/

   enum _Eet_File_Mode
     {
	EET_FILE_MODE_READ,
	EET_FILE_MODE_WRITE
     };
   
   typedef enum _Eet_File_Mode             Eet_File_Mode;
   
   typedef struct _Eet_File                Eet_File;
   typedef struct _Eet_Data_Descriptor     Eet_Data_Descriptor;


/***************************************************************************/
   
   /* eet_open - Open an eet file on disk, and returns a handle to it.
    * @file:     The file path to the eet file. eg: "/tmp/file.eet".
    * @mode:     The mode for opening. Either EET_FILE_MODE_READ or EET_FILE_MODE_WRITE, but not both.
    * 
    * This function will open an exiting eet file for reading, and build
    * the directory table in memory and return a handle to the file, if it
    * exists and can be read, and no memory errors occur on the way, otherwise
    * NULL will be returned.
    * 
    * It will also open an eet file for writing. This will, if successful,
    * delete the original file and replace it with a new empty file, till
    * the eet file handle is closed or flushed. If it cannot be opened for
    * writing or a memory error occurs, NULL is returned.
    */   
   Eet_File *eet_open  (char *file, Eet_File_Mode mode);
   /* eet_close - Close an eet file handle and flush and writes pending.
    * @ef:        A valid eet file handle.
    * 
    * This function will flush any pending writes to disk if the eet file
    * was opened for write, and free all data associated with the file handle
    * and file, and close the file.
    * 
    * If the eet file handle is not valid nothing will be done.
    */
   void      eet_close (Eet_File *ef);
   /* eet_read - Read a specified entry from an eet file and return data
    * @ef:       A valid eet file handle opened for reading.
    * @name:     Name of the entry. eg: "/base/file_i_want".
    * @size_ret: Number of bytes read from entry and returned.
    * 
    * This function finds an entry in the eet file that is stored under the
    * name specified, and returns that data, decompressed, if successfule.
    * NULL is retuurned if the lookup fails or if memory errors are
    * encountered. It is the job of the calling program to call free() on
    * the returned data. The number of bytes in the returned data chunk are
    * placed in size_ret.
    * 
    * If the eet file handle is not valid NULl is returned and size_ret is
    * filled with 0.
    */
   void     *eet_read  (Eet_File *ef, char *name, int *size_ret);
   /* eet_write - Write a specified entry to an eet file handle
    * @ef:        A valid eet file handle opened for writing.
    * @name:      Name of the entry. eg: "/base/file_i_want".
    * @data:      Pointer to the data to be stored.
    * @size:      Length in bytes in the data to be stored.
    * @compress:  Compression flags (1 == compress, 0 = don't compress).
    * 
    * This function will write the specified chunk of data to the eet file
    * and return 1 on success. 0 will be returned on failure.
    * 
    * The eet file handle must be a valid file handle for an eet file opened 
    * for writing. If it is not, 0 will be returned and no action will be
    * performed.
    * 
    * Name, and data must not be NULL, and size must be > 0. If these
    * conditions are not met, 0 will be returned.
    * 
    * The data will be copied (and optionally compressed) in ram, pending
    * a flush to disk (it will stay in ram till the eet file handle is
    * closed though).
    */
   int       eet_write (Eet_File *ef, char *name, void *data, int size, int compress);
   /* eet_list  - List all entries in eet file matching shell glob.
    * @ef:        A valid eet file handle.
    * @glob:      A shell glob to match against.
    * @count_ret: number of entries foudn to match.
    * 
    * This function will list all entries in the eet file matching the
    * supplied shell glob and return an allocated list of their names, if
    * there are any, and if no memory errors occur.
    * 
    * The eet file handle must be valid and glob must not be NULL, or NULL
    * will be returned and count_ret will be filled with 0.
    * 
    * The calling program must call free() on the array returned, but NOT
    * on the string pointers in the array. They are taken as read-only
    * internals from the eet file handle. They are only valid as long as
    * the file handle is not closed. When it is closed those pointers in the
    * array are now not valid and should not be used.
    * 
    * On success the array returned will have a list of string pointers
    * that are the names of the entries that matched, and count_ret will have
    * the number of entries in this array placed in it.
    * 
    * Hint: an easy way to list all entries in an eet file is to use a glob
    * value of "*".
    */
   char    **eet_list  (Eet_File *ef, char *glob, int *count_ret);

/***************************************************************************/
   
   /* eet_data_image_read - Read image data from the named key in the eet file.
    * @ef:                  A valid eet file handle opened for reading.
    * @name:                Name of the entry. eg: "/base/file_i_want".
    * @w:                   A pointer to the int to hold the width in pixels.
    * @h:                   A pointer to the int to hold the height in pixels.
    * @alpha:               A pointer to the int to hold the alpha flag.
    * @compress:            A pointer to the int to hold the compression amount.
    * @quality:             A pointer to the int to hold the quality amount.
    * @lossy:               A pointer to the int to hold the lossiness flag.
    * 
    * This function reads an image from an eet file stored under the named
    * key in the eet file and return a pointer to the decompressed pixel data.
    * 
    * The other parameters of the image (width, height etc.) are placed into
    * the values pointed to (they must be supplied). The pixel data is a linear
    * array of pixels starting from the top-left of the image scanning row by 
    * row from left to right. Each piel is a 32bit value, with the high byte
    * being the alpha channel, the next being red, then green, and the low byte
    * being blue. The width and height are measured in pixels and will be
    * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
    * that the alpha channel is not used. 1 denoties that it is significant.
    * Compress is fiulled with the compression value/amount the image was
    * stored with. The quality value si fileld with the quality encoding of
    * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
    * the image was encoded lossily or not.
    * 
    * On success the function returns a pointer to the image data decoded. The
    * calling application is responsible for calling free() on the image data
    * when it is done with it. On failure NULL is returned and the parameter
    * values may not contain any sensible data.
    */
   void     *eet_data_image_read(Eet_File *ef, char *name, int *w, int *h, int *alpha, int *compress, int *quality, int *lossy);
   /* eet_data_image_write - Write image data to the named key in an eet file.
    * @ef:                   A valid eet file handle opened for writing.
    * @name:                 Name of the entry. eg: "/base/file_i_want".
    * @data:                 A pointer to the image pixel data.
    * @w:                    The width of the image in pixels.
    * @h:                    The height of the image in pixels.
    * @alpha:                The alpha channel flag.
    * @compress:             The compression amount.
    * @quality:              The quality encoding amount.
    * @lossy:                The lossiness flag.
    * 
    * This function dates image pixel data and encodes it in an eet file
    * stored under the supplied name key, and returns how many bytes were
    * actually written to encode the image data.
    * 
    * The data expected is the same format as returned by eet_data_image_read.
    * If this is not the case wierd things may happen. Width and height must
    * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
    * the alpha values are not useful and 1 meaning they are). Compress can
    * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
    * This is only used if the image is not lossily encoded. Quality is used on
    * lossy compression and shoudl be a value from 0 to 100. The lossy flag
    * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
    * image quality loss (but then have a much smaller encoding).
    * 
    * On success this function rtuens the numebr fo bytes that were required
    * to encode the image data, or on failure it returns 0.
    */   
   int       eet_data_image_write(Eet_File *ef, char *name, void *data, int w, int h, int alpha, int compress, int quality, int lossy);

   /* To Be Documented
    * 
    */
   void     *eet_data_image_encode(void *data, int *size_ret, int w, int h, int alpha, int compress, int quality, int lossy);
   void     *eet_data_image_decode(void *data, int size, int *w, int *h, int *alpha, int *compress, int *quality, int *lossy);
/***************************************************************************/
   
   /* To Be Documented
    * 
    */
   Eet_Data_Descriptor *eet_data_descriptor_new(char *name, int size, void *(*func_list_next) (void *l), void *(*func_list_append) (void *l, void *d), void *(*func_list_data) (void *l), void  (*func_hash_foreach) (void *h, int (*func) (void *h, const char *k, void *dt, void *fdt), void *fdt), void *(*func_hash_add) (void *h, const char *k, void *d));
   void                 eet_data_descriptor_free(Eet_Data_Descriptor *edd);
   
   void  eet_data_descriptor_element_add(Eet_Data_Descriptor *edd, char *name, int type, int group_type, int offset, int count, char *counter_name, Eet_Data_Descriptor *subtype);
   
   void *eet_data_read(Eet_File *ef, Eet_Data_Descriptor *edd, char *name);
   int   eet_data_write(Eet_File *ef, Eet_Data_Descriptor *edd, char *name, void *data, int compress);
   
   void *eet_data_descriptor_decode(Eet_Data_Descriptor *edd, void *data_in, int size_in);
   void *eet_data_descriptor_encode(Eet_Data_Descriptor *edd, void *data_in, int *size_ret);

#define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \
     { \
	struct_type ___ett; \
	\
	eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN, \
					(char *)(&(___ett.member)) - (char *)(&(___ett)), \
					0, NULL, NULL); \
     }
#define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype) \
     { \
	struct_type ___ett; \
	\
	eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN, \
					(char *)(&(___ett.member)) - (char *)(&(___ett)), \
					0, NULL, subtype); \
     }
#define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype) \
     { \
	struct_type ___ett; \
	\
	eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST, \
					(char *)(&(___ett.member)) - (char *)(&(___ett)), \
					0, NULL, subtype); \
     }
   
/***************************************************************************/
#ifdef __cplusplus
}
#endif

#endif