Writing images to mplay

Houdini provides a program called imdisplay which will send an image to a running mplay (or start mplay if required). This document describes the interface for communicating with imdisplay

Sample Programs

  • tomdisplay.C is a simple program that shows how to transmit a single image to mplay.

  • 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]; }
  • The magic_number is used to recognize the format. If the number is reverse endian between the writer and imdisplay all the data will automatically be byte-swapped.
  • The resolution of the image is specified in the xres and yres fields.
  • 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