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

TIL_TextureMap - for filtered evaluation of DSM/DCM's)
IMG_DeepPixelReader - For thread-safe reading of DSM pixels
IMG_DeepShadowChannel

Examples:: standalone/dsmprint.C, and standalone/i3ddsmgen.C.

Definition at line 344 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 515 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 484 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 540 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 378 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 584 of file IMG_DeepShadow.h.

friend class IMG_DeepPixelWriter

friend

Definition at line 585 of file IMG_DeepShadow.h.

friend class img_DeepShadow

friend

Definition at line 591 of file IMG_DeepShadow.h.

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

IMG/IMG_DeepShadow.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation