1 #ifndef PLY_H 2 #define PLY_H 3 /* ---------------------------------------------------------------------- 4 * RPly library, read/write PLY files 5 * Diego Nehab, Princeton University 6 * http://www.cs.princeton.edu/~diego/professional/rply 7 * 8 * This library is distributed under the MIT License. See notice 9 * at the end of this file. 10 * ---------------------------------------------------------------------- */ 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 #define RPLY_VERSION "RPly 1.01" 17 #define RPLY_COPYRIGHT "Copyright (C) 2003-2005 Diego Nehab" 18 #define RPLY_AUTHORS "Diego Nehab" 19 20 /* ---------------------------------------------------------------------- 21 * Types 22 * ---------------------------------------------------------------------- */ 23 /* structures are opaque */ 24 typedef struct t_ply_ *p_ply; 25 typedef struct t_ply_element_ *p_ply_element; 26 typedef struct t_ply_property_ *p_ply_property; 27 typedef struct t_ply_argument_ *p_ply_argument; 28 29 /* ply format mode type */ 30 typedef enum e_ply_storage_mode_ { 31 PLY_BIG_ENDIAN, 32 PLY_LITTLE_ENDIAN, 33 PLY_ASCII, 34 PLY_DEFAULT /* has to be the last in enum */ 35 } e_ply_storage_mode; /* order matches ply_storage_mode_list */ 36 37 /* ply data type */ 38 typedef enum e_ply_type { 39 PLY_INT8, PLY_UINT8, PLY_INT16, PLY_UINT16, 40 PLY_INT32, PLY_UIN32, PLY_FLOAT32, PLY_FLOAT64, 41 PLY_CHAR, PLY_UCHAR, PLY_SHORT, PLY_USHORT, 42 PLY_INT, PLY_UINT, PLY_FLOAT, PLY_DOUBLE, 43 PLY_LIST /* has to be the last in enum */ 44 } e_ply_type; /* order matches ply_type_list */ 45 46 /* ---------------------------------------------------------------------- 47 * Property reading callback prototype 48 * 49 * message: error message 50 * ---------------------------------------------------------------------- */ 51 typedef void (*p_ply_error_cb)(const char *message); 52 53 /* ---------------------------------------------------------------------- 54 * Opens a ply file for reading (fails if file is not a ply file) 55 * 56 * error_cb: error callback function 57 * name: file name 58 * 59 * Returns 1 if successful, 0 otherwise 60 * ---------------------------------------------------------------------- */ 61 p_ply ply_open(const char *name, p_ply_error_cb error_cb); 62 63 /* ---------------------------------------------------------------------- 64 * Reads and parses the header of a ply file returned by ply_open 65 * 66 * ply: handle returned by ply_open 67 * 68 * Returns 1 if successfull, 0 otherwise 69 * ---------------------------------------------------------------------- */ 70 int ply_read_header(p_ply ply); 71 72 /* ---------------------------------------------------------------------- 73 * Property reading callback prototype 74 * 75 * argument: parameters for property being processed when callback is called 76 * 77 * Returns 1 if should continue processing file, 0 if should abort. 78 * ---------------------------------------------------------------------- */ 79 typedef int (*p_ply_read_cb)(p_ply_argument argument); 80 81 /* ---------------------------------------------------------------------- 82 * Sets up callbacks for property reading after header was parsed 83 * 84 * ply: handle returned by ply_open 85 * element_name: element where property is 86 * property_name: property to associate element with 87 * read_cb: function to be called for each property value 88 * pdata/idata: user data that will be passed to callback 89 * 90 * Returns 0 if no element or no property in element, returns the 91 * number of element instances otherwise. 92 * ---------------------------------------------------------------------- */ 93 long ply_set_read_cb(p_ply ply, const char *element_name, 94 const char *property_name, p_ply_read_cb read_cb, 95 void *pdata, long idata); 96 97 /* ---------------------------------------------------------------------- 98 * Returns information about the element originating a callback 99 * 100 * argument: handle to argument 101 * element: receives a the element handle (if non-null) 102 * instance_index: receives the index of the current element instance 103 * (if non-null) 104 * 105 * Returns 1 if successfull, 0 otherwise 106 * ---------------------------------------------------------------------- */ 107 int ply_get_argument_element(p_ply_argument argument, 108 p_ply_element *element, long *instance_index); 109 110 /* ---------------------------------------------------------------------- 111 * Returns information about the property originating a callback 112 * 113 * argument: handle to argument 114 * property: receives the property handle (if non-null) 115 * length: receives the number of values in this property (if non-null) 116 * value_index: receives the index of current property value (if non-null) 117 * 118 * Returns 1 if successfull, 0 otherwise 119 * ---------------------------------------------------------------------- */ 120 int ply_get_argument_property(p_ply_argument argument, 121 p_ply_property *property, long *length, long *value_index); 122 123 /* ---------------------------------------------------------------------- 124 * Returns user data associated with callback 125 * 126 * pdata: receives a copy of user custom data pointer (if non-null) 127 * idata: receives a copy of user custom data integer (if non-null) 128 * 129 * Returns 1 if successfull, 0 otherwise 130 * ---------------------------------------------------------------------- */ 131 int ply_get_argument_user_data(p_ply_argument argument, void **pdata, 132 long *idata); 133 134 /* ---------------------------------------------------------------------- 135 * Returns the value associated with a callback 136 * 137 * argument: handle to argument 138 * 139 * Returns the current data item 140 * ---------------------------------------------------------------------- */ 141 double ply_get_argument_value(p_ply_argument argument); 142 143 /* ---------------------------------------------------------------------- 144 * Reads all elements and properties calling the callbacks defined with 145 * calls to ply_set_read_cb 146 * 147 * ply: handle returned by ply_open 148 * 149 * Returns 1 if successfull, 0 otherwise 150 * ---------------------------------------------------------------------- */ 151 int ply_read(p_ply ply); 152 153 /* ---------------------------------------------------------------------- 154 * Iterates over all elements by returning the next element. 155 * Call with NULL to return handle to first element. 156 * 157 * ply: handle returned by ply_open 158 * last: handle of last element returned (NULL for first element) 159 * 160 * Returns element if successfull or NULL if no more elements 161 * ---------------------------------------------------------------------- */ 162 p_ply_element ply_get_next_element(p_ply ply, p_ply_element last); 163 164 /* ---------------------------------------------------------------------- 165 * Iterates over all comments by returning the next comment. 166 * Call with NULL to return pointer to first comment. 167 * 168 * ply: handle returned by ply_open 169 * last: pointer to last comment returned (NULL for first comment) 170 * 171 * Returns comment if successfull or NULL if no more comments 172 * ---------------------------------------------------------------------- */ 173 const char *ply_get_next_comment(p_ply ply, const char *last); 174 175 /* ---------------------------------------------------------------------- 176 * Iterates over all obj_infos by returning the next obj_info. 177 * Call with NULL to return pointer to first obj_info. 178 * 179 * ply: handle returned by ply_open 180 * last: pointer to last obj_info returned (NULL for first obj_info) 181 * 182 * Returns obj_info if successfull or NULL if no more obj_infos 183 * ---------------------------------------------------------------------- */ 184 const char *ply_get_next_obj_info(p_ply ply, const char *last); 185 186 /* ---------------------------------------------------------------------- 187 * Returns information about an element 188 * 189 * element: element of interest 190 * name: receives a pointer to internal copy of element name (if non-null) 191 * ninstances: receives the number of instances of this element (if non-null) 192 * 193 * Returns 1 if successfull or 0 otherwise 194 * ---------------------------------------------------------------------- */ 195 int ply_get_element_info(p_ply_element element, const char** name, 196 long *ninstances); 197 198 /* ---------------------------------------------------------------------- 199 * Iterates over all properties by returning the next property. 200 * Call with NULL to return handle to first property. 201 * 202 * element: handle of element with the properties of interest 203 * last: handle of last property returned (NULL for first property) 204 * 205 * Returns element if successfull or NULL if no more properties 206 * ---------------------------------------------------------------------- */ 207 p_ply_property ply_get_next_property(p_ply_element element, 208 p_ply_property last); 209 210 /* ---------------------------------------------------------------------- 211 * Returns information about a property 212 * 213 * property: handle to property of interest 214 * name: receives a pointer to internal copy of property name (if non-null) 215 * type: receives the property type (if non-null) 216 * length_type: for list properties, receives the scalar type of 217 * the length field (if non-null) 218 * value_type: for list properties, receives the scalar type of the value 219 * fields (if non-null) 220 * 221 * Returns 1 if successfull or 0 otherwise 222 * ---------------------------------------------------------------------- */ 223 int ply_get_property_info(p_ply_property property, const char** name, 224 e_ply_type *type, e_ply_type *length_type, e_ply_type *value_type); 225 226 /* ---------------------------------------------------------------------- 227 * Creates new ply file 228 * 229 * name: file name 230 * storage_mode: file format mode 231 * 232 * Returns handle to ply file if successfull, NULL otherwise 233 * ---------------------------------------------------------------------- */ 234 p_ply ply_create(const char *name, e_ply_storage_mode storage_mode, 235 p_ply_error_cb error_cb); 236 237 /* ---------------------------------------------------------------------- 238 * Adds a new element to the ply file created by ply_create 239 * 240 * ply: handle returned by ply_create 241 * name: name of new element 242 * ninstances: number of element of this time in file 243 * 244 * Returns 1 if successfull, 0 otherwise 245 * ---------------------------------------------------------------------- */ 246 int ply_add_element(p_ply ply, const char *name, long ninstances); 247 248 /* ---------------------------------------------------------------------- 249 * Adds a new property to the last element added by ply_add_element 250 * 251 * ply: handle returned by ply_create 252 * name: name of new property 253 * type: property type 254 * length_type: scalar type of length field of a list property 255 * value_type: scalar type of value fields of a list property 256 * 257 * Returns 1 if successfull, 0 otherwise 258 * ---------------------------------------------------------------------- */ 259 int ply_add_property(p_ply ply, const char *name, e_ply_type type, 260 e_ply_type length_type, e_ply_type value_type); 261 262 /* ---------------------------------------------------------------------- 263 * Adds a new list property to the last element added by ply_add_element 264 * 265 * ply: handle returned by ply_create 266 * name: name of new property 267 * length_type: scalar type of length field of a list property 268 * value_type: scalar type of value fields of a list property 269 * 270 * Returns 1 if successfull, 0 otherwise 271 * ---------------------------------------------------------------------- */ 272 int ply_add_list_property(p_ply ply, const char *name, 273 e_ply_type length_type, e_ply_type value_type); 274 275 /* ---------------------------------------------------------------------- 276 * Adds a new property to the last element added by ply_add_element 277 * 278 * ply: handle returned by ply_create 279 * name: name of new property 280 * type: property type 281 * 282 * Returns 1 if successfull, 0 otherwise 283 * ---------------------------------------------------------------------- */ 284 int ply_add_scalar_property(p_ply ply, const char *name, e_ply_type type); 285 286 /* ---------------------------------------------------------------------- 287 * Adds a new comment item 288 * 289 * ply: handle returned by ply_create 290 * comment: pointer to string with comment text 291 * 292 * Returns 1 if successfull, 0 otherwise 293 * ---------------------------------------------------------------------- */ 294 int ply_add_comment(p_ply ply, const char *comment); 295 296 /* ---------------------------------------------------------------------- 297 * Adds a new obj_info item 298 * 299 * ply: handle returned by ply_create 300 * comment: pointer to string with obj_info data 301 * 302 * Returns 1 if successfull, 0 otherwise 303 * ---------------------------------------------------------------------- */ 304 int ply_add_obj_info(p_ply ply, const char *obj_info); 305 306 /* ---------------------------------------------------------------------- 307 * Writes the ply file header after all element and properties have been 308 * defined by calls to ply_add_element and ply_add_property 309 * 310 * ply: handle returned by ply_create 311 * 312 * Returns 1 if successfull, 0 otherwise 313 * ---------------------------------------------------------------------- */ 314 int ply_write_header(p_ply ply); 315 316 /* ---------------------------------------------------------------------- 317 * Writes one property value, in the order they should be written to the 318 * file. For each element type, write all elements of that type in order. 319 * For each element, write all its properties in order. For scalar 320 * properties, just write the value. For list properties, write the length 321 * and then each of the values. 322 * 323 * ply: handle returned by ply_create 324 * 325 * Returns 1 if successfull, 0 otherwise 326 * ---------------------------------------------------------------------- */ 327 int ply_write(p_ply ply, double value); 328 329 /* ---------------------------------------------------------------------- 330 * Closes a ply file handle. Releases all memory used by handle 331 * 332 * ply: handle to be closed. 333 * 334 * Returns 1 if successfull, 0 otherwise 335 * ---------------------------------------------------------------------- */ 336 int ply_close(p_ply ply); 337 338 #ifdef __cplusplus 339 } 340 #endif 341 342 #endif /* RPLY_H */ 343 344 /* ---------------------------------------------------------------------- 345 * Copyright (C) 2003-2005 Diego Nehab. All rights reserved. 346 * 347 * Permission is hereby granted, free of charge, to any person obtaining 348 * a copy of this software and associated documentation files (the 349 * "Software"), to deal in the Software without restriction, including 350 * without limitation the rights to use, copy, modify, merge, publish, 351 * distribute, sublicense, and/or sell copies of the Software, and to 352 * permit persons to whom the Software is furnished to do so, subject to 353 * the following conditions: 354 * 355 * The above copyright notice and this permission notice shall be 356 * included in all copies or substantial portions of the Software. 357 * 358 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 359 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 360 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 361 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 362 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 363 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 364 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 365 * ---------------------------------------------------------------------- */ 366