IDLgrImage::ReadFilteredData

The IDLgrImage::ReadFilteredData function method returns image data after a shader program (contained in an IDLgrShader object or object subclassed from IDLgrShader) has been applied, or after one or more shaders (contained in an IDLgrFilterChain object) have been applied.

Note: If there is sufficient hardware support for IDLgrShader programs, this method will complete the shader operations and read the results generated by the graphic card’s GPU (Graphic Processing Unit). If there is insufficient support or if software rendering has been specified, the software-based alternative will be used if you have provided one.

Syntax

Result = Obj->[IDLgrImage::]ReadFilteredData( Dest [, DATA_TYPE=value] [, READ_POSITION=value] [, TILE=tileinfo] )

Return Value

Returns an array containing the filtered image data. The returned array is always of dimensions [4, w, h] where w is the width of the returned image and h is the height. The data is always pixel interleaved RGBA. The type of the returned data is determined by the DATA_TYPE keyword.

If there was an error this method returns 0.

Arguments

Dest

A object reference to a graphics destination object, (e.g. IDLgrWindow).

Keywords

DATA_TYPE

Set this to one of the following allowable values to specify the data type of the returned data:

0	BYTE (default)
1	INT
2	FLOAT
3	UINT

The output of shader programs is always floating point so if 0, 1, or 3 is specified, the output is clamped to the range of 0.0 to 1.0 and then scaled to fill the requested data type range. If 2 is specified, the data is returned unmodified. The data is converted from floating point to the requested type as follows:

Requested Type	Conversion from Floating Point (f)
BYTE (0)	c = (2⁸-1)f
INT (1)	c = [(2¹⁶-1)f -1]/2
FLOAT (2)	c = f
UINT (3)	c = (2¹⁶-1)f

Note: It is very important that this keyword and the IDLgrShader OUTPUT_DATA_TYPE property are set in a consistent manner. For example, suppose you have UINT image data, but OUTPUT_DATA_TYPE is set to BYTE while DATA_TYPE is set to UINT. You will lose accuracy (due to the intermediate BYTE stage). In this example OUTPUT_DATA_TYPE should be set to FLOAT32 (or possibly FLOAT16 if only 10-bits of the UINT are used).

If not set, BYTE data is returned by default.

READ_POSITION

When the IDLgrImage SHADER property has been set to an IDLgrFilterChain object, set this keyword to a scalar long value specifying the zero-based position in the chain from which the data should be read.

For instance, if the filter chain contains a series of 3 shader objects, setting this keyword to one of the following values returns the specified data:

0 reads the result without any shaders applied
1 reads the result after application of only the first shader
2 reads the result after application of the first and second shaders
3 reads the result after application of all three shaders

If this keyword isn't set then the default behavior is to return the image data after application of all filtering shaders in the filter chain.

TILE

If the IDLgrImage is tiled (TILING=1) then this keyword must be set to a valid IDLIMAGETILE structure specifying the tile or tiles for which to return filtered data. For example, to retrieve the filtered data for the currently visible tiles call IDLgrWindow::QueryRequiredTiles, /ALL_VISIBLE, then for each tile call ReadFilteredData.

Note: Data must be loaded into the tiles using IDLgrImage::SetTileData before doing this.

An error will be generated if the image is tiled and this keyword is not set to a valid IDLIMAGETILE structure.

Examples

Create an instance of the example object, shader_rgb_doc, which includes the ability to capture an image and display the results in iImage. Run the example by creating an instance of the object at the IDL command prompt using orgbshader=OBJ_NEW("shader_rgb_doc") or view the file in an IDL Editor window by entering .EDIT shader_rgb_doc__define.

Version History

6.4	Introduced