Debian Codegraph @

Contrib/DtexToExr/README

raw
1 //-*****************************************************************************
2
3 Pixar's Dtex to Exr conversion utility
4 Aug 1, 2012 - first checkin to OpenEXR 2.0 branch of OpenEXR git repository.
5
6 This utility converts a DTEX deep shadow file to an OpenEXR 2.0 deep exr file,
7 formerly, ".odz" (or .dexr, or whatever extension your facility may use). As of
8 the first checkin, the utility only supports 1, 3, or 4-channel dtex files,
9 corresponding to deep alpha or deep RGBA only. The Nuke DTEX reader, which
10 uses basically the same code, will support a more complete arbitrary channel
11 set, and this utility may be upgraded as well. We also only support a single
12 view for the time being.
13
14 DTEX has a complicated set of interpretations, which represent six separate
15 code paths for conversion to the deep representation in OpenEXR 2.0. They
16 represent the permutations of these exemplary Display Driver config strings
17 to prman:
18
19 Display "+filename.dtex" "deepshad" "deepopacity" "string volumeinterpretation" "continuous"
20 Display "+filename.dtex" "deepshad" "deepopacity" "string volumeinterpretation" "discrete"
21 Display "+filename.dtex" "deepshad" "a" "string volumeinterpretation" "continuous"
22 Display "+filename.dtex" "deepshad" "a" "string volumeinterpretation" "discrete"
23 Display "+filename.dtex" "deepshad" "rgba" "string volumeinterpretation" "continuous"
24 Display "+filename.dtex" "deepshad" "rgba" "string volumeinterpretation" "discrete"
25
26 In our terminology, these six options are called:
27
28 OneChanDeepOpacityContinuous
29 OneChanDeepOpacityDiscrete
30 OneChanDeepAlphaContinuous
31 OneChanDeepAlphaDiscrete
32 FourChanDeepRgbaContinuous
33 FourChanDeepRgbaDiscrete
34
35 Renderman will write out both 1-channel and 3-channel opacity in the
36 "deepopacity" case, which we currently only use the first channel of, as
37 we are only targeting a single opacity curve in space. This may evolve in
38 the future.
39
40 There are weird gotchas for each of these 6 cases, and they are documented
41 in the PxDeepUtils.h file, along with specific comments in each of the six
42 header files that correspond to each case:
43
44 PxOneChanDeepOpacityContinuous.h
45 PxOneChanDeepOpacityDiscrete.h
46 PxOneChanDeepAlphaContinuous.h
47 PxOneChanDeepAlphaDiscrete.h
48 PxFourChanDeepRgbaContinuous.h
49 PxFourChanDeepRgbaDiscrete.h
50
51 The gotchas relate to several issues, mostly to do with coincident or
52 out-of-order samples, precision issues, compression artifacts, and the
53 differences between the "deepopacity" vs "deepalpha" interpretations.
54
55 With "deepopacity" (the pre-prman 16 usage), opacity values stored in
56 dtex files were accumulated, so they were bounded between 0 and 1. The
57 values stored are actually not opacities, but rather transmissivities
58 (1-opacity), and monotonically decreased from fully transparent (1)
59 to fully opaque (0). This representation is ideal for meaningful error
60 minimization during compression, and also for usage as a shadow map
61 by a renderer, because the extinction at a particular depth, at a
62 particular pixel, can be evaluated with a single look-up. However,
63 this representation is poor for deep compositing, because each of the
64 samples includes data from smaller depth samples, and recombination is
65 difficult. With these types of files, when using volumetric (continuous)
66 interpretation, the samples represent the accumulated transmissivity at
67 the NEAR SIDE of a depth span, and our code paths take this into account.
68
69 With all other usages - "a" and "rgba", the values represent filtered
70 samples of the given field at that point in space. The alpha values
71 will be between 0 and 1, but are not guaranteed to be increasing or
72 decreasing. This presents a strange problem for volumetric interpretation,
73 as what does it mean to describe the alpha of an infintesimally small
74 region of space (point sample). The best interpretation of the data
75 in this case uses the alpha to represent the accumulated opacity of
76 the region of space nearer than the sample, and thus each sample
77 represents the FAR SIDE of a depth span. Our code paths take this into
78 account as well.
79
80 Please see the files for additional comments, and the command
81 "dtexToExr" may be run with -h, --h, --help, or no arguments to
82 print its usage.
83
84 -Christopher Horvath, Aug 2012, Pixar
85