RenderManAPI  24.0
dtex.h
Go to the documentation of this file.
1 /*
2 # ------------------------------------------------------------------------------
3 #
4 # Copyright (c) 2020 Pixar. All rights reserved.
5 #
6 # The information in this file (the "Software") is provided for the exclusive
7 # use of the software licensees of Pixar ("Licensees"). Licensees have the
8 # right to incorporate the Software into other products for use by other
9 # authorized software licensees of Pixar, without fee. Except as expressly
10 # permitted herein, the Software may not be disclosed to third parties, copied
11 # or duplicated in any form, in whole or in part, without the prior written
12 # permission of Pixar.
13 #
14 # The copyright notices in the Software and this entire statement, including the
15 # above license grant, this restriction and the following disclaimer, must be
16 # included in all copies of the Software, in whole or in part, and all permitted
17 # derivative works of the Software, unless such copies or derivative works are
18 # solely in the form of machine-executable object code generated by a source
19 # language processor.
20 #
21 # PIXAR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
22 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL PIXAR BE
23 # LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
24 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
25 # OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
26 # CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. IN NO CASE WILL
27 # PIXAR'S TOTAL LIABILITY FOR ALL DAMAGES ARISING OUT OF OR IN CONNECTION WITH
28 # THE USE OR PERFORMANCE OF THIS SOFTWARE EXCEED $50.
29 #
30 # Pixar
31 # 1200 Park Ave
32 # Emeryville CA 94608
33 #
34 # ------------------------------------------------------------------------------
35 */
36 
37 #ifndef DTEX_H
38 #define DTEX_H
39 
40 /*
41  ******
42  NOTICE: The dtex API is now deprecated and will be removed
43  in a future release
44  ******
45 
46  *
47  * libdtex
48  *
49  * This library provides the structures and functions necessary to create,
50  * load, and modify deep texture map files. It maintains a tile cache
51  * under the covers, making it possible to work on files without loading
52  * them entirely into memory.
53  *
54  * The API supports an arbitrary number of images in a single file, each
55  * with its own resolution, tile size, and view matrices.
56  *
57  * The library can read and write old deep shadow files in addition to
58  * newer, more general deep texture files. Deep shadow files are
59  * limited to a single sub-image, but otherwise have the same API as the
60  * newer interface.
61  */
62 
63 
64 #include "prmanapi.h" // for PRMANAPI, uint64_t
65 
66 /* The following struct types aren't exported; users may only
67  access members through the API calls defined below. */
68 
69 typedef struct DtexFile DtexFile;
70 typedef struct DtexImage DtexImage;
71 typedef struct DtexMetadata DtexMetadata;
72 typedef struct DtexPixel DtexPixel;
73 typedef struct DtexCache DtexCache;
75 
76 /* DtexCreate and DtexOpen let the user specify their
77  own file access functions, in case read() and write() aren't
78  good enough. Following are the types for these functions: */
79 
80 typedef void *(*DtexCreateFunc)(const char *name);
81 typedef void *(*DtexOpenFunc)(const char *name, const char *mode);
82 typedef long (*DtexReadFunc)(void *handle, char *data, long seek, long size);
83 typedef long (*DtexWriteFunc)(void *handle, char *data, long seek, long size);
84 typedef void (*DtexCloseFunc)(void *handle);
85 
86 /* DtexAccessor encapsulates the various file access functions. A
87  pointer to one of these can be passed to DtexCreate() or
88  DtexOpen() if nonstandard file access methods are needed. */
89 
90 typedef struct DtexAccessor
91 {
92  DtexCreateFunc createFunc; /* function to create a file */
93  DtexOpenFunc openFunc; /* function to open a file */
94  DtexReadFunc readFunc; /* function to read from a file handle */
95  DtexWriteFunc writeFunc; /* function to write to a file handle */
96  DtexCloseFunc closeFunc; /* function to close a file handle */
97 } DtexAccessor;
98 
99 /* The following types are similiar, but add support for large 2GB+ files
100  * with 64 bit offsets. */
101 
102 typedef long (*DtexLargeReadFunc)(void *handle, char *data, uint64_t seek, long size);
103 typedef long (*DtexLargeWriteFunc)(void *handle, char *data, uint64_t seek, long size);
104 
105 typedef struct DtexLargeAccessor
106 {
107  DtexLargeReadFunc readFunc; /* function to read from a file handle */
108  DtexLargeWriteFunc writeFunc; /* function to write to a file handle */
110 
111 /* Tile compression type. */
112 typedef enum DtexCompression
113 {
119 } DtexCompression;
120 
121 /* Type of data stored with each pixel. (Note that the depth is always
122  stored as a float. */
123 typedef enum DtexDataType
124 {
130 } DtexDataType;
131 
132 /* Error codes: */
133 
134 enum{
135  DTEX_NOMETADATA = -14, /* Metadata entry was not found or was invalid */
136  DTEX_BADCHANNEL = -13, /* Channel mismatch between pixels or tiles */
137  DTEX_READONLY = -12, /* Attempt to modify file loaded as read only */
138  DTEX_CAPACITY = -11, /* Tried to go past 2GB on a small capacity file */
139  DTEX_TILECOMPRESSION = -10, /* Something happened during tile compression */
140  DTEX_UNFINISHED = -9, /* Illegal operation on pixel with unresolved
141  compression state */
142  DTEX_RANGE = -8, /* Out of range parameter */
143  DTEX_NOMEM = -7, /* Ran out of memory */
144  DTEX_EMPTY = -6, /* Illegal operation on an empty structure */
145  DTEX_NOIMAGE = -5, /* The specified image was not found */
146  DTEX_UNSUPPORTED = -4, /* The specified operation is not supported. */
147  DTEX_BADFILE = -3, /* File was corrupt */
148  DTEX_NOFILE = -2, /* File was not found or was invalid */
149  DTEX_ERR = -1, /* File was not found or was invalid */
150  DTEX_NOERR = 0 /* No worries */
151 };
152 
153 #ifdef __cplusplus
154 extern "C" {
155 #endif
156 
157 /*
158  *********************************************************************
159  * CACHE FUNCTIONS:
160  *********************************************************************
161  *
162  * The following functions are used to maintain deep texture tile
163  * caches.
164  */
165 
166 /* ----------------------------------------------------------------- */
167 
168 PRMANAPI extern DtexCache * DtexCreateCache(int numTiles,
169  DtexAccessor *accessor);
170 /*
171  * create a new tile cache. accessor specifies a set of I/O functions
172  * to use upon faults. If accessor is NULL, standard system calls
173  * are used.
174  */
175 
176 /* ----------------------------------------------------------------- */
177 
179  int numTilesPerThread, DtexAccessor *accessor,
180  DtexLargeAccessor *largeAccessor);
181 /*
182  * Create a new tile cache that is safe for read-only use in a
183  * multithreaded environment. Accessor specifies a set of I/O functions to
184  * use upon faults. LargeAccessor provides 64-bit offset versions. If
185  * either is NULL, standard system call are used.
186  */
187 
188 /* ----------------------------------------------------------------- */
189 
191  DtexLargeAccessor *accessor);
192 
193 /*
194  * Specify a set of I/O functions to use upon faults when dealing with
195  * large capacity files. If not called, default implementations using
196  * standard system calls are used.
197  */
198 
199 /* ----------------------------------------------------------------- */
200 
201 PRMANAPI extern int DtexDestroyCache(DtexCache *c);
202 
203 /* ----------------------------------------------------------------- */
204 
205 PRMANAPI extern int DtexSyncCache(DtexCache *dsc);
206 
207 /*
208  * write out all modified tiles of all files in the cache, causing the
209  * files on disk to reflect any changes that have been made.
210  */
211 
212 /* ----------------------------------------------------------------- */
213 
214 /*
215  *********************************************************************
216  * FILE OPENING/CLOSING FUNCTIONS:
217  *********************************************************************
218  *
219  * The following functions are used to create new deep texture files,
220  * or to open existing deep texture files.
221  */
222 
223 /* ----------------------------------------------------------------- */
224 
225 PRMANAPI extern int DtexIsDeepFile(const char *name,
226  DtexCache *cache,
227  int *version);
228 /*
229  * Attempt to open a file with the given filename, and check whether it
230  * appears to be a deep texture file. Returns DTEX_NOERR and sets version
231  * to the file format version if the file is a deep texture file.
232  */
233 
234 /* ----------------------------------------------------------------- */
235 
236 PRMANAPI extern int DtexOpenFile(const char *name,
237  const char *mode,
238  DtexCache *cache,
239  DtexFile **result);
240 /*
241  * Open a deep texture file with the given filename, managed by the
242  * given cache.
243  */
244 
245 /* ----------------------------------------------------------------- */
246 
247 PRMANAPI extern int DtexCreateFile(const char *name,
248  DtexCache *cache,
249  DtexFile **result);
250 
251 /*
252  * Open a deep texture file with the given filename, managed by the
253  * given cache.
254  */
255 
256 /* ----------------------------------------------------------------- */
257 
258 #define DTEX_CREATE_FILE_PARAMS_VERSION 1
259 
260 typedef struct {
261  int version; // DTEX_CREATE_FILE_PARAMS_VERSION
264 
265 PRMANAPI extern int DtexCreateFileEx(const char *name,
266  DtexCache *cache,
267  DtexFile **result,
268  DtexCreateFileParams *params);
269 
270 /*
271  * Open a deep texture file with the given filename, managed by the
272  * given cache. Force new format
273  */
274 
275 /* ----------------------------------------------------------------- */
276 
277 PRMANAPI extern int DtexFileVersion(DtexFile *f);
278 /*
279  * return the format version of the given file.
280  */
281 
282 /* ----------------------------------------------------------------- */
283 
284 PRMANAPI extern int DtexGetFileMetadata(DtexFile *f, DtexMetadata **result);
285 /*
286  * return a handle to the file-wide metadata.
287  */
288 
289 /* ----------------------------------------------------------------- */
290 
291 PRMANAPI extern int DtexAddImage(DtexFile *f,
292  const char *name,
293  int numChan,
294  int w, int h,
295  int tw, int th, /* tile width and height */
296  float *NP,
297  float *Nl,
298  enum DtexCompression compression,
299  enum DtexDataType datatype,
300  DtexImage **result);
301 /*
302  * Add an image to the given file.
303  */
304 
305 /* ----------------------------------------------------------------- */
306 
307 #define DTEX_DEEPOPACITY_VERSION 1
308 #define DTEX_AREASHADOW_VERSION 1
309 #define DTEX_DEEPCOMP_VERSION 1
310 
311 #define DTEX_ADD_IMAGE_PARAMS_VERSION 1
312 
313 typedef struct {
314  int version; // DTEX_ADD_IMAGE_PARAMS_VERSION
315  char const *formatType; // "deepopacity", "areashadow", or "deepcomp"
316  int formatVersion; // DTEX_DEEPOPACITY_VERSION, etc.
318 
319 PRMANAPI extern int DtexAddImageEx(DtexFile *f,
320  const char *name,
321  int numChan,
322  int w, int h,
323  int tw, int th, /* tile width and height */
324  float *NP,
325  float *Nl,
326  enum DtexCompression compression,
327  enum DtexDataType datatype,
328  DtexImage **result,
329  DtexAddImageParams *params);
330 /*
331  * Add an image to the given file. May take additional parameters such as
332  * formatType and formatVersion.
333  */
334 
335 /* ----------------------------------------------------------------- */
336 
337 PRMANAPI extern int DtexCountImages(DtexFile *f);
338 
339 /*
340  * Return the number of images in the given file.
341  */
342 
343 /* ----------------------------------------------------------------- */
344 
345 /*
346  * If the given file contains an image with the given name, return a
347  * pointer to it. Returns DTEX_NOIMAGE if the given image doesn't exist.
348  * The resulting pointer is guaranteed to be valid until DtexClose() is
349  * called on the containing
350  * file.
351  */
352 
353 PRMANAPI extern int DtexGetImageByName(DtexFile *f,
354  const char *name,
355  DtexImage **result);
356 
357 /* ----------------------------------------------------------------- */
358 
359 /*
360  * Return the nth image from the given file. Returns DTEX_NOFILE
361  * if the file doesn't exist, or DTEX_NOIMAGE if the given image doesn't
362  * exist. The resulting pointer is guaranteed to be valid until
363  * DtexClose() is called on the containing file.
364  */
365 
367  int index,
368  DtexImage **result);
369 
370 /* ----------------------------------------------------------------- */
371 
372 PRMANAPI extern int DtexClose(DtexFile *ds);
373 /*
374  * close a deep texture file, writing out all modified tiles.
375  */
376 
377 /* ----------------------------------------------------------------- */
378 
379 PRMANAPI extern int DtexSync(DtexFile *ds);
380 
381 /*
382  * write out all modified tiles of deep texture "ds", causing the
383  * file on disk to reflect any changes that have been made.
384  */
385 
386 /* ----------------------------------------------------------------- */
387 
388 /*
389  *********************************************************************
390  * FILE ACCESS FUNCTIONS:
391  *********************************************************************
392  *
393  * The following functions let the user access and modify the
394  * contents of an open deep texture file.
395  */
396 
397 /* ----------------------------------------------------------------- */
398 
399 PRMANAPI extern int DtexWidth(DtexImage *i);
400 /*
401  * return the width of the given image in pixels
402  */
403 
404 /* ----------------------------------------------------------------- */
405 
406 PRMANAPI extern char *DtexImageName(DtexImage *i);
407 /*
408  * return the name of the given image. The resulting pointer is
409  * guaranteed to be valid until DtexClose() is called on the containing
410  * file.
411  */
412 
413 /* ----------------------------------------------------------------- */
414 
415 PRMANAPI extern int DtexNumChan(DtexImage *i);
416 /*
417  * return the number of channels in the given image
418  */
419 
420 /* ----------------------------------------------------------------- */
421 
422 PRMANAPI extern int DtexHeight(DtexImage *i);
423 /*
424  * return the height of the given image in pixels
425  */
426 
427 /* ----------------------------------------------------------------- */
428 
429 PRMANAPI extern int DtexTileWidth(DtexImage *i);
430 /*
431  * return the width of the tiles in the given image, in pixels
432  */
433 
434 /* ----------------------------------------------------------------- */
435 
436 PRMANAPI extern int DtexTileHeight(DtexImage *i);
437 /*
438  * return the height of the tiles in the given deep texture, in pixels
439  */
440 
441 /* ----------------------------------------------------------------- */
442 
443 PRMANAPI extern int DtexNP(DtexImage *i, float *NP);
444 /*
445  * copy the projection matrix from the given image to NP.
446  */
447 
448 /* ----------------------------------------------------------------- */
449 
450 PRMANAPI extern int DtexNl(DtexImage *i, float *Nl);
451 /*
452  * copy the light-space matrix from the given image to Nl.
453  */
454 
455 /* ----------------------------------------------------------------- */
456 
458 /*
459  * return the compression type of the image.
460  */
461 
462 /* ----------------------------------------------------------------- */
463 
465 /*
466  * return the data type of the image.
467  */
468 
469 /* ----------------------------------------------------------------- */
470 
471 PRMANAPI extern int DtexGetImageMetadata(DtexImage *i, DtexMetadata **result);
472 /*
473  * return a handle to the metadata associated with the image.
474  */
475 
476 /* ----------------------------------------------------------------- */
477 
478 PRMANAPI extern int DtexSetPixelData(DtexImage *img,
479  int x, int y,
480  int numChan,
481  int numPoints,
482  float *data);
483 /*
484  * copy the given pixel data into pixel x,y of the specified image.
485  * numChan indicates how many channels of data are being provided,
486  * and numPoints indicates how many points there are. data should
487  * point to numPoints*(numChan+1) floats.
488  */
489 
490 /* ----------------------------------------------------------------- */
491 
492 PRMANAPI extern int DtexSetPixel(DtexImage *img,
493  int x, int y,
494  DtexPixel *pix);
495 /*
496  * copy the given pixel into pixel x,y of the specified image. pix
497  * must have either the same number of channels as img, or one channel.
498  *
499  * If pix has any unresolved compression state, DTEX_ERR is returned.
500  * Call DtexFinishPixel before you use DtexSetPixel.
501  */
502 
503 /* ----------------------------------------------------------------- */
504 
505 PRMANAPI extern int DtexGetPixel(DtexImage *img,
506  int x, int y,
507  DtexPixel *pix);
508 /*
509  * copy the pixel at position x,y in "ds" into the given pixel
510  * structure. The pixel structure is resized if necessary, and if
511  * the number of channels in pix is different than the number of
512  * channels in img, pix is modified to match.
513  *
514  * Returns DTEX_NOERR if no error, DTEX_RANGE if the requested pixel
515  * is outside the image, or DTEX_BADFILE if the file is found to be
516  * corrupt.
517  */
518 
519 /* ----------------------------------------------------------------- */
520 
521 PRMANAPI extern int DtexEval(DtexImage *img,
522  int x, int y,
523  float z,
524  int n,
525  float *data);
526 /*
527  * look up the pixel's interpolated value at depth z, and put the
528  * result in data. n must indicate how many floats are
529  * allocated in data, and must be no less than the number of
530  * channels in the image.
531  */
532 
533 /* ----------------------------------------------------------------- */
534 
535 PRMANAPI extern int DtexGetZRange(DtexImage *img,
536  int x, int y,
537  float *min,
538  float *max);
539 /*
540  * computes the range over which the specified pixel is defined.
541  * if the pixel is non-empty, the range is returned in min and max
542  * and the function returns DTEX_NOERR. If the pixel is empty,
543  * DTEX_EMPTY is returned and min and max are undefined.
544  */
545 
546 /* ----------------------------------------------------------------- */
547 
548 PRMANAPI extern int DtexGetMeanDepth(DtexImage *img,
549  int x, int y,
550  float *mean,
551  float *alpha);
552 /*
553  * computes the mean depth found in the pixel and the overall
554  * coverage. This is useful for displaying deep images.
555  */
556 
557 /* ----------------------------------------------------------------- */
558 
559 /*
560  *********************************************************************
561  * METADATA STRUCTURE FUNCTIONS:
562  *********************************************************************
563  */
564 
565 /* ----------------------------------------------------------------- */
566 
567 PRMANAPI extern int DtexMetadataSet(DtexMetadata *meta,
568  char const *token,
569  void const *value);
570 /*
571  * Add or update a metadata field associated with an image or file. The
572  * token is a string specifying the type and name of the field and
573  * is given in the standard RenderMan style, e.g., ``float bbox[6]``.
574  * Supported types are: float, int, point, color, vector, normal, hpoint,
575  * matrix, and string.
576  *
577  * The associated data to write is given by the value pointer. In the
578  * case of string data, this should point to ``char *`` pointers that
579  * point to the strings themselves (i.e., argv style). If the value
580  * pointer is null, the metadata field will be removed if it exists.
581  */
582 
583 /* ----------------------------------------------------------------- */
584 
585 PRMANAPI extern int DtexMetadataCount(DtexMetadata *meta);
586 /*
587  * Return how many metadata fields the image has.
588  */
589 
590 /* ----------------------------------------------------------------- */
591 
593  int index,
594  char const **token,
595  void const **value);
596 /*
597  * The metadata fields are retrieved in no particular order.
598  * This function is simply a convenience for enumerating all attached
599  * metadata. Returns DTEX_NOMETADATA if the given field doesn't exists.
600  * The resulting pointers, stored in token and value are valid until
601  * either DtexClose() is called on the containing file, or until
602  * DtexSetMetadata() modifies this particular field. Data behind these
603  * pointers must not be changed.
604  */
605 
606 /* ----------------------------------------------------------------- */
607 
609  char const *name,
610  char const **token,
611  void const **value);
612 /*
613  * Metadata fields may also be retrieved by an unadorned name.
614  */
615 
616 /* ----------------------------------------------------------------- */
617 
618 /*
619  *********************************************************************
620  * PIXEL STRUCTURE FUNCTIONS:
621  *********************************************************************
622  *
623  * Because deep texture pixels are varying in size, a pixel's storage
624  * must be dynamically allocated. This library
625  * provides a type, DtexPixel, which allows users to build and evaluate
626  * pixels. The structure is fairly heavyweight because it stores
627  * auxiliary information related to compression. We don't recommend
628  * allocating an entire image of these structures yourself; keep
629  * a small number of DtexPixel's around, and use DtexSetPixel to
630  * modify a DtexImage.
631  *
632  * The following functions let the user create, modify, and
633  * destroy DtexPixel's. Pixels may be cleared with DtexClearPixel().
634  * New datapoints may be added (in increasing Z order) with
635  * DtexAppendPixel(). If compression is used, a pixel must
636  * be DtexFinish()'ed before lookups can be performed in the pixel.
637  */
638 
639 /* ----------------------------------------------------------------- */
640 
641 PRMANAPI extern DtexPixel * DtexMakePixel(int numChan);
642 /*
643  * create a DtexPixel structure. It should be destroyed with
644  * DtexDestroyPixel, not free().
645  */
646 
647 /* ----------------------------------------------------------------- */
648 
649 PRMANAPI extern void DtexDestroyPixel(DtexPixel *pix);
650 /*
651  * free a DtexPixel structure.
652  */
653 
654 /* ----------------------------------------------------------------- */
655 
656 PRMANAPI extern int DtexClearPixel(DtexPixel *pix, int numChan);
657 /*
658  * set the specified pixel structure to be empty. Its allocation
659  * stays around, but the pixel is marked as empty.
660  */
661 
662 /* ----------------------------------------------------------------- */
663 
664 PRMANAPI extern int DtexEmptyPixel(DtexPixel *pix);
665 
666 /*
667  * Clear out all the allocation in the given pixel, but don't free
668  * the pixel itself.
669  */
670 
671 /* ----------------------------------------------------------------- */
672 
673 PRMANAPI extern int DtexSpecifyPixel(DtexPixel *pix,int numChan,int numPoints,
674  float *data);
675 
676 /*
677  * Set the given pixel to have numChan channels and set its data
678  * directly. Assumes no compression.
679  */
680 
681 /* ----------------------------------------------------------------- */
682 
684 
685 /*
686  * Return 1 if the specific pixel has duplicates for all its values,
687  * zero otherwise. If the pixel has no control points, returns 1.
688  */
689 
690 /* ----------------------------------------------------------------- */
691 
692 PRMANAPI extern int DtexPixelGetNumChan(DtexPixel *pix);
693 /*
694  * Return the number of channels in the pixel.
695  */
696 
697 /* ----------------------------------------------------------------- */
698 
699 PRMANAPI extern int DtexPixelGetNumPoints(DtexPixel *pix);
700 /*
701  * Return the number of control points in the pixel. Returns zero
702  * if there are no control points, -1 if the point has unresolved
703  * compression state.
704  */
705 
706 /* ----------------------------------------------------------------- */
707 
708 PRMANAPI extern int DtexPixelGetPoint(DtexPixel *pix, int i, float *z, float *data);
709 /*
710  * Get the i'th control point in the given pixel. If the indicated
711  * control point is accessible, z and data are set, and DTEX_NOERR
712  * is returned. If the pixel does not exist, DTEX_NOPOINT is
713  * returned and *z and *data are undefined. If the pixel has
714  * unresolved compression state, DTEX_UNFINISHED is returned and
715  * *z and *data are undefined.
716  */
717 
718 /* ----------------------------------------------------------------- */
719 
720 PRMANAPI extern int DtexPixelSetPoint(DtexPixel *pix, int i, float z, float *data);
721 
722 /*
723  * Modify the i'th control point in the given pixel. If the indicated
724  * control point is accessible, and if the supplied z is legal,
725  * the pixel is modified and DTEX_NOERR
726  * is returned. If the pixel does not exist, DTEX_NOPOINT is
727  * returned. If the pixel has unresolved compression state,
728  * DTEX_UNFINISHED is returned and *z and *data are undefined.
729  */
730 
731 /* ----------------------------------------------------------------- */
732 
733 PRMANAPI extern int DtexCopyPixel(DtexPixel *dest,
734  DtexPixel *src);
735 /*
736  * copy src to dest. If dest has a different number of channels
737  * than src, dest is modified to match. This includes current
738  * compression state.
739  */
740 
741 
742 /* ----------------------------------------------------------------- */
743 PRMANAPI extern int DtexMergePixel(DtexPixel *dest,
744  DtexPixel *src);
745 /*
746  * Merges data from src to dest - the resulting data in dest will have
747  * all control points that were present in both pixels. Both pixels
748  * must have the same number of channels, and must not have unresolved
749  * compression state.
750  */
751 
752 PRMANAPI extern int DtexMergePixelEx(DtexPixel *dest, DtexPixel *src,
753  int rgbChannel, int alphaChannel);
754 /*
755  * Like DtexMergePixel, this merges data from src into dest. In addition,
756  * it can correctly handle embedding geometry in volumes and overlapping
757  * volumes. These volume segments are flagged with a negative alpha and
758  * extend to the next sample in the pixel. There must be at least one
759  * non-volume sample marking the end of chain (which may be completely
760  * transparent).
761  *
762  * This assumes a four channel RGBA pixel function when splitting and
763  * merging volume regions. The rgbChannel must be the index of the first
764  * color channel, with the assumption that all three color channels are
765  * contiguous. The alphaChannel must be the index of the alpha channel.
766  * Any additional channels will be copied unchanged from the most recent
767  * volume sample.
768  */
769 
770 /* ----------------------------------------------------------------- */
771 
772 PRMANAPI extern int DtexFinishPixel(DtexPixel *dest);
773 /*
774  * If the specified pixel is in "compress mode" (non-zero compression),
775  * this function finishes compression and sets compression error to zero.
776  * This must be called before any lookups on the pixel structure.
777  *
778  * If the pixel already has a zero compression error, this function has
779  * no effect.
780  */
781 
782 /* ----------------------------------------------------------------- */
783 
784 PRMANAPI extern int DtexAppendPixel(DtexPixel *pix,
785  float z,
786  int n,
787  float *data,
788  float error);
789 /*
790  * add a data point to the end of the specified pixel. n must
791  * specify how many floats are stored in data, and must match
792  * the number of channels in the pixel.
793  */
794 
795 /* ----------------------------------------------------------------- */
796 
797 PRMANAPI extern int DtexEvalPixel(DtexPixel *pix,
798  float z,
799  int n,
800  float *data);
801 /*
802  * evaluate the pixel's function at depth z, and put the
803  * result in data. n must indicate how many floats are
804  * allocated in data, and must be no less than the number of
805  * channels in the image.
806  */
807 
808 
809 /* ----------------------------------------------------------------- */
810 
811 PRMANAPI extern int DtexCompositePixel(DtexPixel *pix,
812  int rgbChannel,
813  int alphaChannel,
814  float *data);
815 /*
816  * Composite a four channel RGBA pixel function and store the result
817  * in data. rgbChannel must be the index of the first color channel,
818  * with the assumption that all three color channels are
819  * contiguous. alphaChannel must be the index of the alpha
820  * channel. data must be a buffer of at least four floats. If the
821  * pixel is empty, DTEX_EMPTY is returned and data is filled with
822  * zeros. Otherwise, data[0], data[1], and data[2] contain the
823  * composited color values and data[3] contains the composited alpha
824  * value, and DTEX_NOERR is returned.
825  */
826 
827 
828 /* ----------------------------------------------------------------- */
829 
830 PRMANAPI extern int DtexGetPixelZRange(DtexPixel *pix,
831  float *min,
832  float *max);
833 /*
834  * computes the range over which the specified pixel is defined.
835  * if the pixel is non-empty, the range is returned in min and max
836  * and the function returns DTEX_NOERR. If the pixel is empty,
837  * DTEX_EMPTY is returned and min and max are undefined. If the pixel
838  * has unresolved compression state, DTEX_UNFINISHED is returned and
839  * min and max are undefined.
840  */
841 
842 /* ----------------------------------------------------------------- */
843 
844 PRMANAPI extern int DtexPrintPixel(DtexPixel *p);
845 /*
846  * print a representation of the given pixel to stdout
847  */
848 
849 /* ----------------------------------------------------------------- */
850 
851 PRMANAPI extern int DtexAveragePixels(int n,
852  DtexPixel **pixels,
853  float *weights,
854  float error,
855  DtexPixel *result);
856 /*
857  * compute the weighted pointwise average of the given pixels and put the
858  * result in result.
859  */
860 
861 /* ----------------------------------------------------------------- */
862 
863 PRMANAPI extern void DtexPrintStats(void);
864 
865 /* ----------------------------------------------------------------- */
866 
867 /* Create a new Deep filter */
868 
870 
871 /* Create a new Deep filter */
872 
873 #define DTEX_CREATE_DEEP_FILTER_PARAMS_VERSION 2
874 
875 typedef struct {
876  // v1...
877  int version;
878  float error;
882  // v2...
883  float deptherror;
885 
887 
888 /* Destroy a new Deep filter */
889 
890 PRMANAPI extern void DtexDestroyDeepFilter(DtexDeepFilter *filter);
891 
892 /*
893  * Prepare the given filter to take samples. numChan is the number of
894  * channels (in addition to z) per delta. numSamples is the number of
895  * samples in the filter. numDeltas is an array with numSamples values
896  * indicating, for each sample, how many deltas are in that sample.
897  * filterWeights is an array with numSamples floats indicating, for each
898  * sample, what that sample's filterweight is. totalNumDeltas is the
899  * sum of the values in numDeltas.
900  *
901  * When this function is done, all the samples will be set up. The
902  * user can then run through and fill in the actual deltas.
903  */
904 
905 PRMANAPI extern float *DtexGetDeepFilterData(DtexDeepFilter *filter,
906  int numChan,
907  int numSamples,
908  int *numDeltas,
909  float *filterWeights,
910  int totalNumDeltas);
911 
912 /* ----------------------------------------------------------------- */
913 
914 /* Execute the given filter to produce point data. pointData must
915  contain enough space to hold "totalNumDeltas" deltas as specified
916  in DtexGetDeepFilterData.
917 
918  If assumeSmooth is non-zero, the computation will assume that the
919  underlying function is smooth, and that any discontinuities encountered
920  are part of the sampling error. It will thus not try to reproduce
921  discontinuities.
922 
923 */
924 
926  float *pointData,
927  float error,
928  int assumeSmooth);
929 
930 /* Execute the given filter to produce point data. pointData must
931  contain enough space to hold "totalNumDeltas" deltas as specified
932  in DtexGetDeepFilterData.
933 
934  If assumeSmooth is non-zero, the computation will assume that the
935  underlying function is smooth, and that any discontinuities encountered
936  are part of the sampling error. It will thus not try to reproduce
937  discontinuities.
938 
939  The filter is assumed to have been configured with relevant error
940  and other configurations via DtexCreateDeepFilterEx
941 */
942 
943 
945  float *pointData);
946 
947 /* ----------------------------------------------------------------- */
948 
949 /* Given a series of points, compress it. */
950 
951 PRMANAPI extern int DtexCompressPointData(float *pointData,
952  int numChan,
953  int numPoints,
954  float *result,
955  float error);
956 
957 /* ----------------------------------------------------------------- */
958 
959 /* Compress one pixel and put the result in another. Doesn't work
960  * in place. (dest must not == src.)
961  */
962 
963 PRMANAPI extern int
964 DtexCompressPixel(DtexPixel *src,DtexPixel *dest,float error);
965 
966 /* ----------------------------------------------------------------- */
967 
968 PRMANAPI extern void
969 DtexQueryMemory(unsigned long *current,unsigned long *peak);
970 
971 #ifdef __cplusplus
972 }
973 #endif
974 
975 #endif /* DTEX_H */
976 
PRMANAPI int DtexMetadataSet(DtexMetadata *meta, char const *token, void const *value)
struct DtexMetadata DtexMetadata
Definition: dtex.h:71
Definition: dtex.h:115
Definition: dtex.h:144
PRMANAPI int DtexEval(DtexImage *img, int x, int y, float z, int n, float *data)
PRMANAPI int DtexMetadataGetByIndex(DtexMetadata *meta, int index, char const **token, void const **value)
PRMANAPI int DtexAppendPixel(DtexPixel *pix, float z, int n, float *data, float error)
PRMANAPI int DtexCompressPixel(DtexPixel *src, DtexPixel *dest, float error)
Definition: dtex.h:128
DtexWriteFunc writeFunc
Definition: dtex.h:95
PRMANAPI int DtexWidth(DtexImage *i)
DtexDataType
Definition: dtex.h:123
PRMANAPI int DtexCreateFileEx(const char *name, DtexCache *cache, DtexFile **result, DtexCreateFileParams *params)
PRMANAPI int DtexIsPixelMonochrome(DtexPixel *p)
PRMANAPI int DtexClearPixel(DtexPixel *pix, int numChan)
struct DtexLargeAccessor DtexLargeAccessor
Definition: dtex.h:126
PRMANAPI int DtexAddImage(DtexFile *f, const char *name, int numChan, int w, int h, int tw, int th, float *NP, float *Nl, enum DtexCompression compression, enum DtexDataType datatype, DtexImage **result)
PRMANAPI int DtexMetadataCount(DtexMetadata *meta)
PRMANAPI int DtexEmptyPixel(DtexPixel *pix)
PRMANAPI int DtexEvalPixel(DtexPixel *pix, float z, int n, float *data)
Definition: dtex.h:135
Definition: dtex.h:127
PRMANAPI float * DtexGetDeepFilterData(DtexDeepFilter *filter, int numChan, int numSamples, int *numDeltas, float *filterWeights, int totalNumDeltas)
#define PRMANAPI
Definition: prmanapi.h:124
Definition: dtex.h:118
PRMANAPI void DtexQueryMemory(unsigned long *current, unsigned long *peak)
int logfunction
Definition: dtex.h:881
PRMANAPI int DtexGetImageByIndex(DtexFile *f, int index, DtexImage **result)
DtexOpenFunc openFunc
Definition: dtex.h:93
PRMANAPI int DtexCompressPointData(float *pointData, int numChan, int numPoints, float *result, float error)
PRMANAPI int DtexHeight(DtexImage *i)
Definition: dtex.h:140
PRMANAPI int DtexIsDeepFile(const char *name, DtexCache *cache, int *version)
PRMANAPI int DtexTileHeight(DtexImage *i)
PRMANAPI int DtexComputeDeepPointData(DtexDeepFilter *filter, float *pointData, float error, int assumeSmooth)
PRMANAPI int DtexGetImageByName(DtexFile *f, const char *name, DtexImage **result)
PRMANAPI DtexPixel * DtexMakePixel(int numChan)
PRMANAPI int DtexDestroyCache(DtexCache *c)
int assumesmooth
Definition: dtex.h:880
DtexCloseFunc closeFunc
Definition: dtex.h:96
PRMANAPI int DtexCountImages(DtexFile *f)
PRMANAPI DtexCompression DtexGetCompression(DtexImage *i)
Definition: dtex.h:116
void *(* DtexCreateFunc)(const char *name)
Definition: dtex.h:80
PRMANAPI void DtexDestroyPixel(DtexPixel *pix)
float deptherror
Definition: dtex.h:883
PRMANAPI int DtexPrintPixel(DtexPixel *p)
PRMANAPI int DtexSync(DtexFile *ds)
DtexLargeReadFunc readFunc
Definition: dtex.h:107
Definition: dtex.h:150
PRMANAPI int DtexNP(DtexImage *i, float *NP)
PRMANAPI int DtexTileWidth(DtexImage *i)
PRMANAPI DtexDataType DtexGetDataType(DtexImage *i)
PRMANAPI int DtexComputeDeepPointDataEx(DtexDeepFilter *filter, float *pointData)
Definition: dtex.h:313
Definition: dtex.h:875
PRMANAPI int DtexPixelSetPoint(DtexPixel *pix, int i, float z, float *data)
PRMANAPI DtexCache * DtexCreateCache(int numTiles, DtexAccessor *accessor)
Definition: dtex.h:137
struct DtexCache DtexCache
Definition: dtex.h:73
Definition: dtex.h:149
PRMANAPI int DtexFinishPixel(DtexPixel *dest)
PRMANAPI int DtexNl(DtexImage *i, float *Nl)
PRMANAPI DtexCache * DtexCreateReadOnlyCache(int numTilesPerThread, DtexAccessor *accessor, DtexLargeAccessor *largeAccessor)
PRMANAPI DtexDeepFilter * DtexCreateDeepFilterEx(DtexCreateDeepFilterParams *p)
PRMANAPI int DtexGetZRange(DtexImage *img, int x, int y, float *min, float *max)
Definition: dtex.h:125
PRMANAPI void DtexDestroyDeepFilter(DtexDeepFilter *filter)
DtexLargeWriteFunc writeFunc
Definition: dtex.h:108
Definition: dtex.h:129
PRMANAPI int DtexSyncCache(DtexCache *dsc)
DtexReadFunc readFunc
Definition: dtex.h:94
PRMANAPI int DtexPixelGetPoint(DtexPixel *pix, int i, float *z, float *data)
struct DtexAccessor DtexAccessor
Definition: dtex.h:145
int version
Definition: dtex.h:261
struct DtexImage DtexImage
Definition: dtex.h:70
float error
Definition: dtex.h:878
PRMANAPI int DtexAveragePixels(int n, DtexPixel **pixels, float *weights, float error, DtexPixel *result)
PRMANAPI void DtexPrintStats(void)
PRMANAPI int DtexCopyPixel(DtexPixel *dest, DtexPixel *src)
int version
Definition: dtex.h:877
void *(* DtexOpenFunc)(const char *name, const char *mode)
Definition: dtex.h:81
long(* DtexWriteFunc)(void *handle, char *data, long seek, long size)
Definition: dtex.h:83
DtexCreateFunc createFunc
Definition: dtex.h:92
struct DtexFile DtexFile
Definition: dtex.h:69
Definition: dtex.h:143
PRMANAPI int DtexMetadataGetByName(DtexMetadata *meta, char const *name, char const **token, void const **value)
PRMANAPI int DtexSetLargeAccessor(DtexCache *c, DtexLargeAccessor *accessor)
PRMANAPI int DtexPixelGetNumChan(DtexPixel *pix)
struct DtexDeepFilter DtexDeepFilter
Definition: dtex.h:74
PRMANAPI int DtexSetPixelData(DtexImage *img, int x, int y, int numChan, int numPoints, float *data)
PRMANAPI int DtexMergePixelEx(DtexPixel *dest, DtexPixel *src, int rgbChannel, int alphaChannel)
Definition: dtex.h:117
long(* DtexLargeReadFunc)(void *handle, char *data, uint64_t seek, long size)
Definition: dtex.h:102
int forceFormatVersion
Definition: dtex.h:262
Definition: dtex.h:260
float simplifyerror
Definition: dtex.h:879
PRMANAPI int DtexGetFileMetadata(DtexFile *f, DtexMetadata **result)
PRMANAPI int DtexGetPixel(DtexImage *img, int x, int y, DtexPixel *pix)
long(* DtexLargeWriteFunc)(void *handle, char *data, uint64_t seek, long size)
Definition: dtex.h:103
PRMANAPI int DtexGetImageMetadata(DtexImage *i, DtexMetadata **result)
PRMANAPI DtexDeepFilter * DtexCreateDeepFilter(void)
PRMANAPI int DtexCreateFile(const char *name, DtexCache *cache, DtexFile **result)
Definition: dtex.h:90
PRMANAPI int DtexGetPixelZRange(DtexPixel *pix, float *min, float *max)
PRMANAPI int DtexGetMeanDepth(DtexImage *img, int x, int y, float *mean, float *alpha)
char const * formatType
Definition: dtex.h:315
struct DtexPixel DtexPixel
Definition: dtex.h:72
Definition: dtex.h:147
int version
Definition: dtex.h:314
Definition: dtex.h:138
Definition: dtex.h:142
long(* DtexReadFunc)(void *handle, char *data, long seek, long size)
Definition: dtex.h:82
Definition: dtex.h:114
PRMANAPI int DtexSetPixel(DtexImage *img, int x, int y, DtexPixel *pix)
PRMANAPI int DtexCompositePixel(DtexPixel *pix, int rgbChannel, int alphaChannel, float *data)
PRMANAPI int DtexOpenFile(const char *name, const char *mode, DtexCache *cache, DtexFile **result)
int formatVersion
Definition: dtex.h:316
void(* DtexCloseFunc)(void *handle)
Definition: dtex.h:84
PRMANAPI int DtexSpecifyPixel(DtexPixel *pix, int numChan, int numPoints, float *data)
Definition: dtex.h:136
Definition: dtex.h:105
PRMANAPI int DtexPixelGetNumPoints(DtexPixel *pix)
PRMANAPI char * DtexImageName(DtexImage *i)
Definition: dtex.h:148
PRMANAPI int DtexNumChan(DtexImage *i)
Definition: dtex.h:146
PRMANAPI int DtexFileVersion(DtexFile *f)
Definition: dtex.h:139
PRMANAPI int DtexClose(DtexFile *ds)
DtexCompression
Definition: dtex.h:112
PRMANAPI int DtexMergePixel(DtexPixel *dest, DtexPixel *src)
PRMANAPI int DtexAddImageEx(DtexFile *f, const char *name, int numChan, int w, int h, int tw, int th, float *NP, float *Nl, enum DtexCompression compression, enum DtexDataType datatype, DtexImage **result, DtexAddImageParams *params)