HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
IMG_DeepShadow Class Reference

Class to read or write deep shadow/camera images. More...

#include <IMG_DeepShadow.h>

Public Member Functions

 IMG_DeepShadow ()
 
virtual ~IMG_DeepShadow ()
 
void setOption (const char *option, const UT_StringHolder &value)
 
void setOption (const char *option, fpreal value)
 
void setOption (const char *option, int64 value)
 
void setOption (const char *option, int value)
 
void setOptions (const UT_Options &options)
 
void printArgs (UT_WorkBuffer &wbuf, bool json)
 Print the current values of the file options into the work buffer. More...
 
const char * getDescription ()
 
bool addExtraChannel (const IMG_DeepShadowChannel &def, const UT_Options *options=0)
 
bool open (const char *name)
 Open a deep shadow map for reading. More...
 
bool pixelStart (int x, int y)
 
bool pixelWrite (float z, const float *data, int vsize)
 
bool pixelWriteOrdered (float z, const float *data, int vsize)
 
bool pixelClose ()
 
bool close ()
 } More...
 
void resolution (int &xres, int &yres) const
 Get the resolution of the deep shadow map. More...
 
int getChannelCount () const
 Get the number of channels in the DSM. More...
 
const IMG_DeepShadowChannel * getChannel (int i) const
 Get a channel definition. More...
 
UT_SharedPtr< UT_Options > getTextureOptions () const
 
bool setTextureOptions (const UT_Options &opts)
 
UT_SharedPtr< IMG_DeepStat > getDeepStat () const
 Return deep stats. More...
 
float ofBias () const
 
float zBias () const
 
const PXL_DeepChannelListPtr & deepChannels () const
 Return the PXL_DeepChannelList being written to the DSM. More...
 
int deepSampleListsPerPixel () const
 Return the number of samples per pixel. More...
 
void setWriteTag (const char *tag, int datasize, const char *const *data)
 Metadata to send to deep image file. More...
 
bool copyImageTextureOptions (const IMG_DeepShadow &src, bool clear_existing)
 
bool create (const char *name, int xres, int yres, int sxres, int syres, float pixel_aspect=1.0, const UT_DimRect *crop=NULL)
 
bool create (const char *name, const IMG_Stat &stat, const IMG_FileParms *options=NULL, const IMG_Format *fmt=NULL)
 

Static Public Member Functions

static void addSpecialChannel (const UT_StringHolder &channel_name, IMG_DeepPlaneMask type)
 
static IMG_DeepPlaneMask isSpecialChannel (const char *name)
 

Protected Member Functions

bool createStat (IMG_Stat &stat, const char *name, int xres, int yres, int sxres, int syres, float pixel_aspect, const UT_DimRect *crop)
 

Friends

class IMG_DeepPixelReader
 
class IMG_DeepPixelWriter
 
class img_DeepShadow
 
template<typename T >
bool getWorldToCamera (UT_Matrix4T< T > &xform) const
 
static bool getWorldToCamera (const UT_Options *options, UT_Matrix4F &xform)
 
static bool getWorldToCamera (const UT_Options *options, UT_Matrix4D &xform)
 
template<typename T >
bool getCameraToNDC (UT_Matrix4T< T > &xform, bool fit_z=true) const
 
static bool getCameraToNDC (const UT_Options *options, UT_Matrix4F &xform, int xres, int yres, bool fit_z=true)
 
static bool getCameraToNDC (const UT_Options *options, UT_Matrix4D &xform, int xres, int yres, bool fit_z=true)
 
template<typename T >
bool getWorldToNDC (UT_Matrix4T< T > &xform, bool fit_z) const
 
static bool getWorldToNDC (const UT_Options *options, UT_Matrix4F &xform, int xres, int yres, bool fit_z)
 
static bool getWorldToNDC (const UT_Options *options, UT_Matrix4D &xform, int xres, int yres, bool fit_z)
 

Detailed Description

Class to read or write deep shadow/camera images.

This class provides a creation interface for deep shadow maps. The class can be used as follows:

setOption(...);
setOption(...);
...
open(fname, xres, yres);
IMG_DeepPixelWriter writer;
foreach pixel loop
writer.open(pixel);
foreach record
writer.write(record);
end loop
writer.close();
end loop
close();

To read from an existing deep shadow map, the class can be used as follows:

IMG_DeepShadow dsm;
IMG_DeepPixelReader pixel;
dsm.open(fname);
foreach (x,y) in raster:
pixel.open(x, y)
for (i = 0; i < pixel.getDepth(); i++)
pixel.getData(chp, i);
close();
See Also
Examples:
standalone/dsmprint.C, and standalone/i3ddsmgen.C.

Definition at line 324 of file IMG_DeepShadow.h.

Constructor & Destructor Documentation

IMG_DeepShadow::IMG_DeepShadow ( )
virtual IMG_DeepShadow::~IMG_DeepShadow ( )
virtual

Member Function Documentation

bool IMG_DeepShadow::addExtraChannel ( const IMG_DeepShadowChannel &  def,
const UT_Options *  options = 0 
)

Add an extra channel to be stored along with Of and Pz. Any number of channels may be added (though the file size will increase accordingly).

  • The name must be unique among (and not Of or Pz)
  • The float_offset is the offset into the "data" in the IMG_DeepPixelWriter::write() method. Note that the opacity must occupy the first 3 floats of the data array. So, the float_offset must be at least 3.
  • The tuple_size is the number of elements in the channel Currently, this must be 1, 3 or 4.
  • The storage specifies the storage type (and uses the same tokens as the "ofstorage" option (i.e. int8, int16, int32, int64, uint8, uint16, uint32, uint64, real16, real32 or real64. The extra channels must be added before open() is called.
static void IMG_DeepShadow::addSpecialChannel ( const UT_StringHolder &  channel_name,
IMG_DeepPlaneMask  type 
)
static

Certain channel names are reserved as "special" channels. These channels have special interpretations for deep images (i.e. "Z", "ZBack", etc.). Each format registers their special channel names

bool IMG_DeepShadow::close ( )

}

Close the deep shadow map and write it to disk.

Examples:
standalone/i3ddsmgen.C.
bool IMG_DeepShadow::copyImageTextureOptions ( const IMG_DeepShadow &  src,
bool  clear_existing 
)
bool IMG_DeepShadow::create ( const char *  name,
int  xres,
int  yres,
int  sxres,
int  syres,
float  pixel_aspect = 1.0,
const UT_DimRect *  crop = NULL 
)

Open a deep shadow map for writing. This method will return false if there were errors opening the texture. The resolution of the image is specified by xres and yres, while the sxres and syres parameters specify the samples per pixel (i.e. 3x3 sampling). The pixel_aspect is typically 1.0, while the crop can be a NULL ptr.

If the sample resolution is unknown, you can set sxres and syres to 1 (the sampleid should be set to 0).

Examples:
standalone/i3ddsmgen.C.
bool IMG_DeepShadow::create ( const char *  name,
const IMG_Stat &  stat,
const IMG_FileParms *  options = NULL,
const IMG_Format *  fmt = NULL 
)

Open a deep shadow map for writing. This method will return false if there were errors opening the texture. The resolution of the image is specified by xres and yres, while the sxres and syres parameters specify the samples per pixel (i.e. 3x3 sampling). The pixel_aspect is typically 1.0, while the crop can be a NULL ptr.

If the sample resolution is unknown, you can set sxres and syres to 1 (the sampleid should be set to 0).

bool IMG_DeepShadow::createStat ( IMG_Stat &  stat,
const char *  name,
int  xres,
int  yres,
int  sxres,
int  syres,
float  pixel_aspect,
const UT_DimRect *  crop 
)
protected

Perform all computation for creating an image, but don't actually open the IMG_File. This can be done when you want to make sure all the deep information is set up properly, but don't actually want to create the image. One example of this might be when doing distributed rendering.

This takes the same arguments as create().

const PXL_DeepChannelListPtr& IMG_DeepShadow::deepChannels ( ) const

Return the PXL_DeepChannelList being written to the DSM.

int IMG_DeepShadow::deepSampleListsPerPixel ( ) const

Return the number of samples per pixel.

static bool IMG_DeepShadow::getCameraToNDC ( const UT_Options *  options,
UT_Matrix4F &  xform,
int  xres,
int  yres,
bool  fit_z = true 
)
static

Get the camera's projection transform from the file options. Returns false if there was no matrix available. If fit_z is true, the projection will attempt to fit the z coordinates to the NDC near/far to the range (0,1). If the camera:clip option is not saved, this will not be possible (z coordinates will remain unchanged). The method will not fail if there is no camera:clip saved, but the z coordinates will have unexpected values

The method gets the values for the projection matrix from the following options:

  • float camera:zoom
  • int camera:projection (optional, defaults to 0)
  • float image:pixelaspect (optional, defaults to 1)
  • vector4 image:window (optional, defaults to [0, 1, 0, 1])
  • vector2 camera:clip (used iff fit_z is true, defaults to (0,1))
  • float camera:orthowidth (required iff projection != 0)
static bool IMG_DeepShadow::getCameraToNDC ( const UT_Options *  options,
UT_Matrix4D &  xform,
int  xres,
int  yres,
bool  fit_z = true 
)
static

Get the camera's projection transform from the file options. Returns false if there was no matrix available. If fit_z is true, the projection will attempt to fit the z coordinates to the NDC near/far to the range (0,1). If the camera:clip option is not saved, this will not be possible (z coordinates will remain unchanged). The method will not fail if there is no camera:clip saved, but the z coordinates will have unexpected values

The method gets the values for the projection matrix from the following options:

  • float camera:zoom
  • int camera:projection (optional, defaults to 0)
  • float image:pixelaspect (optional, defaults to 1)
  • vector4 image:window (optional, defaults to [0, 1, 0, 1])
  • vector2 camera:clip (used iff fit_z is true, defaults to (0,1))
  • float camera:orthowidth (required iff projection != 0)
template<typename T >
bool IMG_DeepShadow::getCameraToNDC ( UT_Matrix4T< T > &  xform,
bool  fit_z = true 
) const
inline

Get the camera's projection transform from the file options. Returns false if there was no matrix available. If fit_z is true, the projection will attempt to fit the z coordinates to the NDC near/far to the range (0,1). If the camera:clip option is not saved, this will not be possible (z coordinates will remain unchanged). The method will not fail if there is no camera:clip saved, but the z coordinates will have unexpected values

The method gets the values for the projection matrix from the following options:

  • float camera:zoom
  • int camera:projection (optional, defaults to 0)
  • float image:pixelaspect (optional, defaults to 1)
  • vector4 image:window (optional, defaults to [0, 1, 0, 1])
  • vector2 camera:clip (used iff fit_z is true, defaults to (0,1))
  • float camera:orthowidth (required iff projection != 0)

Definition at line 495 of file IMG_DeepShadow.h.

const IMG_DeepShadowChannel* IMG_DeepShadow::getChannel ( int  i) const

Get a channel definition.

Examples:
standalone/dsmprint.C.
int IMG_DeepShadow::getChannelCount ( ) const

Get the number of channels in the DSM.

Examples:
standalone/dsmprint.C.
UT_SharedPtr<IMG_DeepStat> IMG_DeepShadow::getDeepStat ( ) const

Return deep stats.

const char* IMG_DeepShadow::getDescription ( )

Get a description of the available options that can be provided in setOption()

UT_SharedPtr<UT_Options> IMG_DeepShadow::getTextureOptions ( ) const

Get UT_Option structure from the file. These options are stored with the file and may be queried in VEX using teximport().

Examples:
standalone/dsmprint.C.
static bool IMG_DeepShadow::getWorldToCamera ( const UT_Options *  options,
UT_Matrix4F &  xform 
)
static

Extract the worldToCamera transform from a UT_Options. Returns false if there was no matrix available.

This extracts the "space:world" matrix from the UT_Options.

static bool IMG_DeepShadow::getWorldToCamera ( const UT_Options *  options,
UT_Matrix4D &  xform 
)
static

Extract the worldToCamera transform from a UT_Options. Returns false if there was no matrix available.

This extracts the "space:world" matrix from the UT_Options.

template<typename T >
bool IMG_DeepShadow::getWorldToCamera ( UT_Matrix4T< T > &  xform) const
inline

Extract the worldToCamera transform from a UT_Options. Returns false if there was no matrix available.

This extracts the "space:world" matrix from the UT_Options.

Definition at line 464 of file IMG_DeepShadow.h.

static bool IMG_DeepShadow::getWorldToNDC ( const UT_Options *  options,
UT_Matrix4F &  xform,
int  xres,
int  yres,
bool  fit_z 
)
static

Get the world to camera NDC space transform using the file options. Returns false if there is no matrix available. If fit_z is true, the projection will attempt to fit the z coordinates to the NDC near/far to the range (0,1). If the camera:clip option is not saved, this will not be possible (z coordinates will remain unchanged).

Note
This simply returns getWorldToCamera()*getCameraToNDC()
static bool IMG_DeepShadow::getWorldToNDC ( const UT_Options *  options,
UT_Matrix4D &  xform,
int  xres,
int  yres,
bool  fit_z 
)
static

Get the world to camera NDC space transform using the file options. Returns false if there is no matrix available. If fit_z is true, the projection will attempt to fit the z coordinates to the NDC near/far to the range (0,1). If the camera:clip option is not saved, this will not be possible (z coordinates will remain unchanged).

Note
This simply returns getWorldToCamera()*getCameraToNDC()
template<typename T >
bool IMG_DeepShadow::getWorldToNDC ( UT_Matrix4T< T > &  xform,
bool  fit_z 
) const
inline

Get the world to camera NDC space transform using the file options. Returns false if there is no matrix available. If fit_z is true, the projection will attempt to fit the z coordinates to the NDC near/far to the range (0,1). If the camera:clip option is not saved, this will not be possible (z coordinates will remain unchanged).

Note
This simply returns getWorldToCamera()*getCameraToNDC()

Definition at line 520 of file IMG_DeepShadow.h.

static IMG_DeepPlaneMask IMG_DeepShadow::isSpecialChannel ( const char *  name)
static
float IMG_DeepShadow::ofBias ( ) const
bool IMG_DeepShadow::open ( const char *  name)

Open a deep shadow map for reading.

Examples:
standalone/dsmprint.C.
bool IMG_DeepShadow::pixelClose ( )
bool IMG_DeepShadow::pixelStart ( int  x,
int  y 
)

These methods are now deprecated in favor of the IMG_DeepPixelWriter class, which allows thread-safe writes to deep images. {

bool IMG_DeepShadow::pixelWrite ( float  z,
const float *  data,
int  vsize 
)
bool IMG_DeepShadow::pixelWriteOrdered ( float  z,
const float *  data,
int  vsize 
)
void IMG_DeepShadow::printArgs ( UT_WorkBuffer &  wbuf,
bool  json 
)

Print the current values of the file options into the work buffer.

void IMG_DeepShadow::resolution ( int &  xres,
int &  yres 
) const

Get the resolution of the deep shadow map.

Examples:
standalone/dsmprint.C.
void IMG_DeepShadow::setOption ( const char *  option,
const UT_StringHolder &  value 
)

Set a file creation option. Options must be set before the file is opened with open() below.

Currently (and this list may be out of date), the options are:

  • "ofstorage" = one of { "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", "real16", "real32", "real64" }
  • "pzstorage" = one of { "int8" ... "real64" }
  • "ofsize" = one of { "1", "3" }
  • "compression = a value between "0" and "9" (lossyness) - "zbias" = minimum delta between z-values (float value) - "depth_mode" = one of { "nearest", "midpoint", "farthest" } - "depth_interp" = one of { "discrete", "continuous" } - "compositing" = "0" will turn off pre-compositing of the z-records This is recommended when dealing with deep camera maps (i.e. if there are extra channels)
Examples:
standalone/i3ddsmgen.C.
void IMG_DeepShadow::setOption ( const char *  option,
fpreal  value 
)
void IMG_DeepShadow::setOption ( const char *  option,
int64  value 
)
void IMG_DeepShadow::setOption ( const char *  option,
int  value 
)
inline

Definition at line 358 of file IMG_DeepShadow.h.

void IMG_DeepShadow::setOptions ( const UT_Options &  options)

Set options based on the "texture:*" options defined in the UT_Options. The UT_Options will be checked for options:

  • texture:ofstorage
  • texture:pzstorage
  • texture:ofsize
  • etc.
bool IMG_DeepShadow::setTextureOptions ( const UT_Options &  opts)

Store the UT_Options structure in the file. These options are stored with the file and may be queried in VEX using teximport() on load.

void IMG_DeepShadow::setWriteTag ( const char *  tag,
int  datasize,
const char *const *  data 
)

Metadata to send to deep image file.

float IMG_DeepShadow::zBias ( ) const

Friends And Related Function Documentation

friend class IMG_DeepPixelReader
friend

Definition at line 564 of file IMG_DeepShadow.h.

friend class IMG_DeepPixelWriter
friend

Definition at line 565 of file IMG_DeepShadow.h.

friend class img_DeepShadow
friend

Definition at line 571 of file IMG_DeepShadow.h.

The documentation for this class was generated from the following file: