Post-processing tools 2023 R2

shared_memory_image_client.h File Reference

Last update: 17.04.2023

C API for using the EnSight grpc shared memory image transport API. More...

#include <stdint.h>

Go to the source code of this file.

Classes

struct  _SharedMemoryFrame
 

Macros

#define IMAGESTREAM_API_VERSION   "1.0"
 
#define IMAGESTREAM_UNCONNECTED   4
 
#define IMAGESTREAM_RECONNECTING   3
 
#define IMAGESTREAM_NO_FRAMEAVAILABLE   2
 
#define IMAGESTREAM_NO_BUFFERAVAILABLE   1
 
#define IMAGESTREAM_NOERROR   0
 
#define IMAGESTREAM_BAD_ARGS   -1
 
#define IMAGESTREAM_NOT_LOCKED   -2
 
#define IMAGESTREAM_BAD_FILE_SIZE   -3
 
#define IMAGESTREAM_UNABLE_TO_OPEN_FILE   -4
 
#define IMAGESTREAM_UNABLE_TO_MAP_FILE   -5
 
#define IMAGESTREAM_MEMORY_ALLOC_ERROR   -6
 
#define IMAGESTREAM_THREAD_CREATE_ERROR   -7
 
#define IMAGESTREAM_IS_SERVER   -8
 
#define IMAGESTREAM_IS_NOTSERVER   -9
 
#define IMAGESTREAM_FRAME_TOO_LARGE   -10
 
#define IMAGESTREAM_LOCKED   -11
 
#define IMAGESTREAM_OPTIONS_NONE   0x00000000
 
#define IMAGESTREAM_OPTIONS_FLIPVERTICAL   0x00000100
 

Typedefs

typedef int SharedMemoryImageError
 common error codes see the non-hex, non-string IMAGESTREAM macros
 
typedef struct _SharedMemoryImageStream * SharedMemoryImageStream
 image transport stream pointer
 
typedef struct _SharedMemoryFrame * SharedMemoryFrame
 A reference to a frame of imagery. Note it does not own the buffer pointer. More...
 

Functions

SharedMemoryImageError SharedMemoryImageStream_create (const char *filename, uint32_t options, SharedMemoryImageStream *stream)
 SharedMemoryImageStream_create create a stream client instance. More...
 
SharedMemoryImageError SharedMemoryImageStream_lock (SharedMemoryImageStream stream, SharedMemoryFrame *frame)
 SharedMemoryImageStream_lock get a frame of pixels from the server. More...
 
SharedMemoryImageError SharedMemoryImageStream_unlock (SharedMemoryImageStream stream)
 SharedMemoryImageStream_unlock release a frame obtained by SharedMemoryImageStream_lock. More...
 
SharedMemoryImageError SharedMemoryImageStream_destroy (SharedMemoryImageStream stream)
 SharedMemoryImageStream_destroy destroy a stream interface, releasing its resources. More...
 
const char * SharedMemoryImageStream_errorstring (SharedMemoryImageError err)
 SharedMemoryImageStream_errorstring convert an error code into a human string. More...
 

Detailed Description

C API for using the EnSight grpc shared memory image transport API.

Version
1.0

This library implements a shared memory (memory mapped file) image transport system. To use the system, the client needs to do the following:

  1. Create a physical file on disk that will serve as the memory mapped interface.
  2. Make sure the file is large enough to hold 2 frames of imagery at maximum size plus 2K. So if the largest image would be for a 4K display, the file needs to be at least 24M + 2K in size (4K*3bytes/pixel*2 frames).
  3. Make an EnSight grpc SubscribeImages() call with SubscribeImageOptions.type=GRPC and the name of the file created in the previous step passed with the "filename" key in SubscribeImageOptions.options. Note: that SubscribeImageOptions.prefix needs to be set to a unique string that will identify this channel. It is suggested that a GUID be used.
  4. The EnSight grpc server will initialize the shared memory communication block and register it with the 'prefix' passed in the SubscribeImages() call. If the shared memory system can be constructed, it returns success.
  5. On successful return from SubscribeImages(), the client then calls SharedMemoryImageStream_create() to connect to the server.
    SharedMemoryImageStream stream;
    SharedMemoryImageError err;
    err = SharedMemoryImageStream_create("shared_memory_file",
    IMAGESTREAM_OPTIONS_NONE, &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
    IMAGESTREAM_OPTIONS_NONE
    #define IMAGESTREAM_OPTIONS_NONE
    Definition: shared_memory_image_client.h:103
    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
  6. Periodically, the client checks for a new image:
    SharedMemoryFrame frame;
    if (IMAGESTREAM_NOERROR == SharedMemoryImageStream_lock(stream, &frame)) {
    <work on the pixels returned in 'frame'>
    SharedMemoryImageStream_unlock(stream);
    }
    SharedMemoryImageStream_unlock
    SharedMemoryImageError SharedMemoryImageStream_unlock(SharedMemoryImageStream stream)
    SharedMemoryImageStream_unlock release a frame obtained by SharedMemoryImageStream_lock.
    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

    If a lock is successful, the frame will be valid and the shared memory system potentially blocked until unlock is called. Once unlock is called, the data returned in frame is no longer valid.

  7. When the communication is finished, the client should make the grpc Unsubscribe() call with the same prefix passed in (3) and then 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.h.

Macro Definition Documentation

◆ IMAGESTREAM_API_VERSION

#define IMAGESTREAM_API_VERSION   "1.0"

The current API version

Definition at line 81 of file shared_memory_image_client.h.

◆ IMAGESTREAM_BAD_ARGS

#define IMAGESTREAM_BAD_ARGS   -1

one of the input parameters is invalid

Definition at line 90 of file shared_memory_image_client.h.

◆ IMAGESTREAM_BAD_FILE_SIZE

#define IMAGESTREAM_BAD_FILE_SIZE   -3

the shared memory file is too small (<10MB) or non-existant

Definition at line 92 of file shared_memory_image_client.h.

◆ IMAGESTREAM_FRAME_TOO_LARGE

#define IMAGESTREAM_FRAME_TOO_LARGE   -10

the image frame is too large for the size of the shared memory file

Definition at line 99 of file shared_memory_image_client.h.

◆ IMAGESTREAM_IS_NOTSERVER

#define IMAGESTREAM_IS_NOTSERVER   -9

the call is not valid for shared memory client to make

Definition at line 98 of file shared_memory_image_client.h.

◆ IMAGESTREAM_IS_SERVER

#define IMAGESTREAM_IS_SERVER   -8

the call is not valid for shared memory server to make

Definition at line 97 of file shared_memory_image_client.h.

◆ IMAGESTREAM_LOCKED

#define IMAGESTREAM_LOCKED   -11

this call is not legal until the stream has been unlocked

Definition at line 100 of file shared_memory_image_client.h.

◆ IMAGESTREAM_MEMORY_ALLOC_ERROR

#define IMAGESTREAM_MEMORY_ALLOC_ERROR   -6

insufficient system memory for internal object allocation

Definition at line 95 of file shared_memory_image_client.h.

◆ IMAGESTREAM_NO_BUFFERAVAILABLE

#define IMAGESTREAM_NO_BUFFERAVAILABLE   1

Not an error, but there were no free buffers to put the frame into

Definition at line 87 of file shared_memory_image_client.h.

◆ IMAGESTREAM_NO_FRAMEAVAILABLE

#define IMAGESTREAM_NO_FRAMEAVAILABLE   2

Not an error, but there was no frame available to read

Definition at line 86 of file shared_memory_image_client.h.

◆ IMAGESTREAM_NOERROR

#define IMAGESTREAM_NOERROR   0

Operation successful

Definition at line 88 of file shared_memory_image_client.h.

◆ IMAGESTREAM_NOT_LOCKED

#define IMAGESTREAM_NOT_LOCKED   -2

an attempt was made to unlock without it having been locked

Definition at line 91 of file shared_memory_image_client.h.

◆ IMAGESTREAM_OPTIONS_FLIPVERTICAL

#define IMAGESTREAM_OPTIONS_FLIPVERTICAL   0x00000100

this is a server flag that requests that pixels be flipped vertically relative to the input buffer

Definition at line 105 of file shared_memory_image_client.h.

◆ IMAGESTREAM_OPTIONS_NONE

#define IMAGESTREAM_OPTIONS_NONE   0x00000000

the default options for a client stream

Definition at line 103 of file shared_memory_image_client.h.

◆ IMAGESTREAM_RECONNECTING

#define IMAGESTREAM_RECONNECTING   3

The stream being connected to was already active, this may or may not be an error

Definition at line 85 of file shared_memory_image_client.h.

◆ IMAGESTREAM_THREAD_CREATE_ERROR

#define IMAGESTREAM_THREAD_CREATE_ERROR   -7

unable to create background processing threads

Definition at line 96 of file shared_memory_image_client.h.

◆ IMAGESTREAM_UNABLE_TO_MAP_FILE

#define IMAGESTREAM_UNABLE_TO_MAP_FILE   -5

the shared memory file could not be memory mapped

Definition at line 94 of file shared_memory_image_client.h.

◆ IMAGESTREAM_UNABLE_TO_OPEN_FILE

#define IMAGESTREAM_UNABLE_TO_OPEN_FILE   -4

the shared memory file could not be opened with necessary permissions

Definition at line 93 of file shared_memory_image_client.h.

◆ IMAGESTREAM_UNCONNECTED

#define IMAGESTREAM_UNCONNECTED   4

Not an error, but no client is listening to the stream

Definition at line 84 of file shared_memory_image_client.h.

Typedef Documentation

◆ SharedMemoryFrame

typedef struct _SharedMemoryFrame * SharedMemoryFrame

A reference to a frame of imagery. Note it does not own the buffer pointer.

Structure representing a frame of imagery in sequence

Function Documentation

◆ SharedMemoryImageStream_create()

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

SharedMemoryImageStream_create create a stream client instance.

This function will map the file pointed to by filename as shared memory an use it to stream images between two applications. The file must (1) exist, (2) be at least 20MB in size and (3) be opened by a server stream before the client stream is created. Once created, the stream interface handle must be destroyed by SharedMemoryImageStream_destroy to release the stream resources.

The file to be used as the shared memory map should be at least 2x the size of the largest image that will be used. For example if you want to transport 4K images, the file should be at least 4000pixels*3bytes/pixel*2 + 500bytes in size. The file must be on a filesystem that support memory mapped I/O.

Negative error codes are a failure of the operation for various reasons. The IMAGESTREAM_RECONNECTING error code can occur if the file has been (or currently is) already supporting a stream and may or may not be an actual error.

Note: server instances can be created using undocumented option flags.

Parameters
[in]filename- the name of a pre-existing file to use as the shared memory window
[in]options- stream creation options
[out]stream- if the returned error value is >=0, this pointer will be returned.
Returns
SharedMemoryImageError - the error code for this call.

◆ SharedMemoryImageStream_destroy()

SharedMemoryImageError SharedMemoryImageStream_destroy ( SharedMemoryImageStream  stream)

SharedMemoryImageStream_destroy destroy a stream interface, releasing its resources.

This function is called to shutdown one end of an image transport stream. It can be the client or server end of the stream.

Parameters
[in]stream- the stream to use
Returns
SharedMemoryImageError - error code for the operation

◆ SharedMemoryImageStream_errorstring()

const char* SharedMemoryImageStream_errorstring ( SharedMemoryImageError  err)

SharedMemoryImageStream_errorstring convert an error code into a human string.

For a given SharedMemoryImageError error code, return a const char * pointer to a utf8 encoded string with a human readable description of the error.

Parameters
[in]err- the error code
Returns
const char * - The string describing the error (utf8 encoding)

◆ SharedMemoryImageStream_lock()

SharedMemoryImageError SharedMemoryImageStream_lock ( SharedMemoryImageStream  stream,
SharedMemoryFrame *  frame 
)

SharedMemoryImageStream_lock get a frame of pixels from the server.

This call should be made periodically by the client application to read images from the server. If the function returns IMAGESTREAM_NOERROR, then the frame argument contains the raw pixel data and the data pointer in that structure is valid until SharedMemoryImageStream_unlock() is called. If the function returns IMAGESTREAM_NO_FRAMEAVAILABLE, no new imagery is available from the server and SharedMemoryImageStream_unlock() does not need to be called.

The frame structure is filled out by this call and the buffer field will be a pointer to the packed RGB image array in row major RBG order. The pointer will point to iWidth*iHeight*3 bytes of data. iFrame will be the frame number. The frame number will always increase, but there may be gaps in the numbering, depending on the render vs image read speeds.

The buffer pointer must not be deallocated by the application.

Parameters
[in]stream- the stream to check for imagery
[out]frame- the currently available image (if any)
Returns
SharedMemoryImageError - the error code for the operation.

◆ SharedMemoryImageStream_unlock()

SharedMemoryImageError SharedMemoryImageStream_unlock ( SharedMemoryImageStream  stream)

SharedMemoryImageStream_unlock release a frame obtained by SharedMemoryImageStream_lock.

If SharedMemoryImageStream_lock() was called and returned IMAGESTREAM_NOERROR, this function must be called to release the frame back to the stream manager. Note, after making this call, the calling application should no longer access any of the fields in the frame returned by the locking call.

Parameters
[in]stream- the stream to use
Returns
SharedMemoryImageError - error code for the operation

Connect with Ansys