deepmplay.C is a simple program that
shows how to transmit a deep raster image to mplay.
Sending Data
When imdisplay is started with the -p option, it will
read data from stdin and pass the data through to
mplay.
The first data sent is the header packet. This describes the image
which is to be read. The header consists of 8 integers (32 bit) and
has the following structure:
struct image_header {
int magic_number = (('h'<<24)+('M'<<16)+('P'<<8)+'0');
int xres;
int yres;
int single_image_storage;
int single_image_array_size;
int multi_plane_count;
int reserved[2];
}
Data Format
The data format for channel data is specified using the following
mapping:
1 | 8 bit unsigned char data |
2 | 16 bit unsigned integer data |
4 | 32 bit unsigned integer data |
0 | 32 bit floating point data |
Array Size
The array size is limited to either 1, 3 or 4 channels per plane.
Other array sizes are not currently supported and will cause
imdisplay to exit with an error status.
Sending a single image plane
This interface is the simplest way to transmit data to mplay. The
multi_plane_count in the header must be set to 0. The
single_image_storage and single_image_array_size fields
must be set to the desired values.
Sending a deep raster (multi-plane image)
The single_image_storage and single_image_array_size
fields must be set to 0. The multi_plane_count in the header
should be set to the number of planes in the image. For example, if
sending an image with "C", "s" and "N" planes, the plane count should
be 3. It's also possible to send single plane images by setting the
count to 1.
When transmitting a deep raster, the plane definitions need to be sent
prior to sending any image data. Each plane is defined by 8 integers
followed by the plane name.
struct plane_definition {
int plane_number; // Sequentially increasing integer
int name_length; // The length of the plane name
int data_format; // Format of the data
int array_size; // Array size of the data
int reserved[4];
}
The plane name should be unique. The length of the name
transmitted in the header should be the number of bytes sent (with or
without the terminating null character).
Sending Tile Data
Image data is sent to imdisplay in tiles. Tiles may be sent in
any random order. They can be any size, but must be constrained to
the image resolution specified. For example, it's possible to send
each scanline of the image in a tile which is one pixel high and the
resolution of the image wide. Alternatively, it's possible (though
not memory efficent) to send the entire image in a single tile.
Prior to sending each tile, a tile header is transmitted. The header
consists of 4 integers:
struct tile_header {
int x0, x1;
int y0, y1;
};
The tile coordinates are specified as inclusive coordinates. That is,
to send a tile which is 16x32 pixels at the bottom left corner of the
image, the tile coordinates would be
tile_header.x0 = 0;
tile_header.x0 = 15;
tile_header.y0 = 0;
tile_header.y0 = 31;
After the header is sent, the raw data for the tile is sent.
Tile Data For Deep Rasters
When sending deep rasters, a special tile header is used to indicate
which plane is being transmitted.
struct plane_select {
int plane_marker = -1;
int plane_index;
int reserved[2];
};
The plane_marker must be set to -1. The plane_index can then be set
to the appropriate index specifying the plane.
When sending multiple planes, the planes must be sent in consecutive
order, starting with plane 0 and ending with the last plane.
Other Applications
hrmanpipe
The hrmanpipe application also uses the same interface for
reading images from stdin as imdisplay. However,
hrmanpipe is used for sending images to destinations other than
mplay. For example, the render state in Houdini or the
RenderMan VOP/SHOP viewer.
The usage for hrmanpipe is
hrmanpipe [-m] [-f] socket_number
Reads an image from stdin and sends the data to the socket specified.
The -f option will cause the image to be flipped (i.e. the first
scanline represents the top of the image).
The -m option should be used when transmitting data to the IPR
viewer.
When a renderer other than mantra is asked to render to the the SHOP
viewer or the render state, the filename for the output driver will be
set to socket:number, where number is the socket number
to be passed to hrmanpipe.
When asked to render to the IPR viewer, the filename will be set to
iprsocket:number. In this case the -m option must be passed to
hrmanpipe