shared_memory_image_client_priv.h File Reference

C API the shared memory image transport API server interface.

Version

1.0

This file describes the internal format of the shared memory system and the inner workings of the buffer state machine. It also provides the interface to a shared memory image server.

When creating a shared memory transport server, the shared_memory_image_client.h interface is used to create/destroy a stream, albeit with unique option flags. The server does not use the SharedMemoryImageStream_lock() / SharedMemoryImageStream_unlock() functions. Instead, it calls SharedMemoryImageStream_putframe() whenever it has new imagery it wants to push to the client.

Server operations are as follows:

1. The client creates/sizes the shared memory file that is to be used and passes the filename to the server.
2. The server creates/initializes the shared memory stream by calling SharedMemoryImageStream_create() with the IMAGESTREAM_OPTIONS_SERVER option.
   SharedMemoryImageStream stream;

   SharedMemoryImageError err;

   err = SharedMemoryImageStream_create("shared_memory_file",

   IMAGESTREAM_OPTIONS_SERVER, &stream);

   if (err < IMAGESTREAM_NOERROR) <handle error>

   SharedMemoryImageStream_create

   SharedMemoryImageError SharedMemoryImageStream_create(const char *filename, uint32_t options, SharedMemoryImageStream *stream)

   SharedMemoryImageStream_create create a stream client instance.

   SharedMemoryImageError

   int SharedMemoryImageError

   common error codes see the non-hex, non-string IMAGESTREAM macros

   Definition: shared_memory_image_client.h:109

   SharedMemoryImageStream

   struct _SharedMemoryImageStream * SharedMemoryImageStream

   image transport stream pointer

   Definition: shared_memory_image_client.h:111

   IMAGESTREAM_NOERROR

   #define IMAGESTREAM_NOERROR

   Definition: shared_memory_image_client.h:88

   IMAGESTREAM_OPTIONS_SERVER

   #define IMAGESTREAM_OPTIONS_SERVER

   Definition: shared_memory_image_client_priv.h:135
3. Periodically, the server may push a new image:
   struct _SharedMemoryFrame frame;

   frame.iFrame = 10;

   frame.iWidth = 640;

   frame.iHeight = 480;

   frame.buffer = <some application buffer at least 648x480x3 bytes in size>;

   SharedMemoryImageError err;

   err = SharedMemoryImageStream_lock(stream, &frame));

   SharedMemoryImageStream_lock

   SharedMemoryImageError SharedMemoryImageStream_lock(SharedMemoryImageStream stream, SharedMemoryFrame *frame)

   SharedMemoryImageStream_lock get a frame of pixels from the server.

   _SharedMemoryFrame

   Definition: shared_memory_image_client.h:115

   _SharedMemoryFrame::iFrame

   uint32_t iFrame

   monotonically increasing frame number

   Definition: shared_memory_image_client.h:116

   _SharedMemoryFrame::buffer

   uint8_t * buffer

   pointer to a packed RGBRGBRGB... (iWidth*iHeight*3) bytes array of pixels

   Definition: shared_memory_image_client.h:119

   The data passed via buffer is copied into the shared memory space. Note, in some conditions, this function does not return a fatal error (<0), instead the error code return can report that no client has made a connection or that the frame was dropped because the client has not been responding to the frames being pushed fast enough.
4. When the communication is finished, the server should call:
   SharedMemoryImageError err = SharedMemoryImageStream_destroy(stream);

   SharedMemoryImageStream_destroy

   SharedMemoryImageError SharedMemoryImageStream_destroy(SharedMemoryImageStream stream)

   SharedMemoryImageStream_destroy destroy a stream interface, releasing its resources.

Definition in file shared_memory_image_client_priv.h.