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