## On this page # shared\_memory\_image\_client\_priv.h File Reference Last update: 16.07.2025 C API the shared memory image transport API server interface. [More...](#details) `#include ` `#include ` `#include ` `#include "shared_memory_image_client.h"` `#include ` `#include ` `#include ` `#include ` `#include ` `#include ` [Go to the source code of this file.](shared__memory__image__client__priv_8h_source.xhtml) ## Macros \#define [IMAGESTREAM\_OPTIONS\_INITBUFFERHEADERS](shared__memory__image__client__priv_8h.xhtml#a24ac2d665ce98370e25639bba2d992b6) 0x00000001 \#define [IMAGESTREAM\_OPTIONS\_NOTHREADS](shared__memory__image__client__priv_8h.xhtml#a673fd1d2f27007af83467699cb53614f) 0x00000002 \#define [IMAGESTREAM\_OPTIONS\_SERVER](shared__memory__image__client__priv_8h.xhtml#aa87740042e4f5882fa4c990a6528c2e3) [IMAGESTREAM\_OPTIONS\_INITBUFFERHEADERS](shared__memory__image__client__priv_8h.xhtml#a24ac2d665ce98370e25639bba2d992b6)|[IMAGESTREAM\_OPTIONS\_NOTHREADS](shared__memory__image__client__priv_8h.xhtml#a673fd1d2f27007af83467699cb53614f) ## Functions DEV [SharedMemoryImageError](shared__memory__image__client_8h.xhtml#a0496a9a3db499fa9145fe97d2e6dae9a) [SharedMemoryImageStream\_putframe](shared__memory__image__client__priv_8h.xhtml#abe3cb5374af97eeccf691864f6e2b2ad) ([SharedMemoryImageStream](shared__memory__image__client_8h.xhtml#af5b8eb2ae90823f10e9a17698ea80749) stream, [SharedMemoryFrame](shared__memory__image__client_8h.xhtml#a995c49496fcc1a41fb2d104c6473223b) frame) SharedMemoryImageStream\_putframe push a new image into a server image stream channel. [More...](shared__memory__image__client__priv_8h.xhtml#abe3cb5374af97eeccf691864f6e2b2ad) ## Detailed Description C API the shared memory image transport API server interface. Version1.0This 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](shared__memory__image__client_8h.xhtml "C API for using the EnSight grpc shared memory image transport API.") interface is used to create/destroy a stream, albeit with unique option flags. The server does not use the [SharedMemoryImageStream\_lock()](shared__memory__image__client_8h.xhtml#afefb8f5297147640b46d1f9eb1e77c9e "SharedMemoryImageStream_lock get a frame of pixels from the server.") / [SharedMemoryImageStream\_unlock()](shared__memory__image__client_8h.xhtml#ac885e449551afd5fb5a7f19c5ec785a6 "SharedMemoryImageStream_unlock release a frame obtained by SharedMemoryImageStream_lock.") functions. Instead, it calls [SharedMemoryImageStream\_putframe()](shared__memory__image__client__priv_8h.xhtml#abe3cb5374af97eeccf691864f6e2b2ad "SharedMemoryImageStream_putframe push a new image into a server image stream channel.") 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()](shared__memory__image__client_8h.xhtml#a03ba052ae823b3e39fef153db8f03ea2 "SharedMemoryImageStream_create create a stream client instance.") with the IMAGESTREAM\_OPTIONS\_SERVER option. [SharedMemoryImageStream](shared__memory__image__client_8h.xhtml#af5b8eb2ae90823f10e9a17698ea80749) stream; [SharedMemoryImageError](shared__memory__image__client_8h.xhtml#a0496a9a3db499fa9145fe97d2e6dae9a) err; err = [SharedMemoryImageStream\_create](shared__memory__image__client_8h.xhtml#a03ba052ae823b3e39fef153db8f03ea2)("shared\_memory\_file", [IMAGESTREAM\_OPTIONS\_SERVER](shared__memory__image__client__priv_8h.xhtml#aa87740042e4f5882fa4c990a6528c2e3), &stream); if (err < [IMAGESTREAM\_NOERROR](shared__memory__image__client_8h.xhtml#af995dd87ffd7dd178eef1d343f7b72bf)) <handle error> [SharedMemoryImageStream\_create](shared__memory__image__client_8h.xhtml#a03ba052ae823b3e39fef153db8f03ea2) SharedMemoryImageError SharedMemoryImageStream_create(const char *filename, uint32_t options, SharedMemoryImageStream *stream) SharedMemoryImageStream_create create a stream client instance. [SharedMemoryImageError](shared__memory__image__client_8h.xhtml#a0496a9a3db499fa9145fe97d2e6dae9a) int SharedMemoryImageError common error codes see the non-hex, non-string IMAGESTREAM macros **Definition:** [shared\_memory\_image\_client.h:109](shared__memory__image__client_8h_source.xhtml#l00109) [SharedMemoryImageStream](shared__memory__image__client_8h.xhtml#af5b8eb2ae90823f10e9a17698ea80749) struct _SharedMemoryImageStream * SharedMemoryImageStream image transport stream pointer **Definition:** [shared\_memory\_image\_client.h:111](shared__memory__image__client_8h_source.xhtml#l00111) [IMAGESTREAM\_NOERROR](shared__memory__image__client_8h.xhtml#af995dd87ffd7dd178eef1d343f7b72bf) \#define IMAGESTREAM_NOERROR **Definition:** [shared\_memory\_image\_client.h:88](shared__memory__image__client_8h_source.xhtml#l00088) [IMAGESTREAM\_OPTIONS\_SERVER](shared__memory__image__client__priv_8h.xhtml#aa87740042e4f5882fa4c990a6528c2e3) \#define IMAGESTREAM_OPTIONS_SERVER **Definition:** [shared\_memory\_image\_client\_priv.h:135](shared__memory__image__client__priv_8h_source.xhtml#l00135) 3. Periodically, the server may push a new image: struct [\_SharedMemoryFrame](struct___shared_memory_frame.xhtml) frame; frame.[iFrame](struct___shared_memory_frame.xhtml#a412d63c3ef8e7417be98997f72f3b0e5) = 10; frame.iWidth = 640; frame.iHeight = 480; frame.buffer = <some application [buffer](struct___shared_memory_frame.xhtml#a7cff19a44525e74c5800b1e2f9e4cc98) at least 648x480x3 bytes in size>; [SharedMemoryImageError](shared__memory__image__client_8h.xhtml#a0496a9a3db499fa9145fe97d2e6dae9a) err; err = [SharedMemoryImageStream\_lock](shared__memory__image__client_8h.xhtml#afefb8f5297147640b46d1f9eb1e77c9e)(stream, &frame)); [SharedMemoryImageStream\_lock](shared__memory__image__client_8h.xhtml#afefb8f5297147640b46d1f9eb1e77c9e) SharedMemoryImageError SharedMemoryImageStream_lock(SharedMemoryImageStream stream, SharedMemoryFrame *frame) SharedMemoryImageStream_lock get a frame of pixels from the server. [\_SharedMemoryFrame](struct___shared_memory_frame.xhtml) **Definition:** [shared\_memory\_image\_client.h:115](shared__memory__image__client_8h_source.xhtml#l00115) [\_SharedMemoryFrame::iFrame](struct___shared_memory_frame.xhtml#a412d63c3ef8e7417be98997f72f3b0e5) uint32_t iFrame monotonically increasing frame number **Definition:** [shared\_memory\_image\_client.h:116](shared__memory__image__client_8h_source.xhtml#l00116) [\_SharedMemoryFrame::buffer](struct___shared_memory_frame.xhtml#a7cff19a44525e74c5800b1e2f9e4cc98) uint8_t * buffer pointer to a packed RGBRGBRGB... (iWidth*iHeight*3) bytes array of pixels **Definition:** [shared\_memory\_image\_client.h:119](shared__memory__image__client_8h_source.xhtml#l00119) 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](shared__memory__image__client_8h.xhtml#a0496a9a3db499fa9145fe97d2e6dae9a) err = [SharedMemoryImageStream\_destroy](shared__memory__image__client_8h.xhtml#a4ea47b6bda387b71ed5f91db329eff65)(stream); [SharedMemoryImageStream\_destroy](shared__memory__image__client_8h.xhtml#a4ea47b6bda387b71ed5f91db329eff65) SharedMemoryImageError SharedMemoryImageStream_destroy(SharedMemoryImageStream stream) SharedMemoryImageStream_destroy destroy a stream interface, releasing its resources. Definition in file [shared\_memory\_image\_client\_priv.h](shared__memory__image__client__priv_8h_source.xhtml). ## Macro Definition Documentation ## [◆ ](#a24ac2d665ce98370e25639bba2d992b6)IMAGESTREAM\_OPTIONS\_INITBUFFERHEADERS \#define IMAGESTREAM\_OPTIONS\_INITBUFFERHEADERS 0x00000001 set if the create call should initialize the buffer state Definition at line [132](shared__memory__image__client__priv_8h_source.xhtml#l00132) of file [shared\_memory\_image\_client\_priv.h](shared__memory__image__client__priv_8h_source.xhtml). ## [◆ ](#a673fd1d2f27007af83467699cb53614f)IMAGESTREAM\_OPTIONS\_NOTHREADS \#define IMAGESTREAM\_OPTIONS\_NOTHREADS 0x00000002 if set, the mutex and monitoring thread will not be created Definition at line [133](shared__memory__image__client__priv_8h_source.xhtml#l00133) of file [shared\_memory\_image\_client\_priv.h](shared__memory__image__client__priv_8h_source.xhtml). ## [◆ ](#aa87740042e4f5882fa4c990a6528c2e3)IMAGESTREAM\_OPTIONS\_SERVER \#define IMAGESTREAM\_OPTIONS\_SERVER [IMAGESTREAM\_OPTIONS\_INITBUFFERHEADERS](shared__memory__image__client__priv_8h.xhtml#a24ac2d665ce98370e25639bba2d992b6)|[IMAGESTREAM\_OPTIONS\_NOTHREADS](shared__memory__image__client__priv_8h.xhtml#a673fd1d2f27007af83467699cb53614f) these options should be set for server streams Definition at line [135](shared__memory__image__client__priv_8h_source.xhtml#l00135) of file [shared\_memory\_image\_client\_priv.h](shared__memory__image__client__priv_8h_source.xhtml). ## Function Documentation ## [◆ ](#abe3cb5374af97eeccf691864f6e2b2ad)SharedMemoryImageStream\_putframe() DEV [SharedMemoryImageError](shared__memory__image__client_8h.xhtml#a0496a9a3db499fa9145fe97d2e6dae9a) SharedMemoryImageStream\_putframe ( [SharedMemoryImageStream](shared__memory__image__client_8h.xhtml#af5b8eb2ae90823f10e9a17698ea80749) *stream*, [SharedMemoryFrame](shared__memory__image__client_8h.xhtml#a995c49496fcc1a41fb2d104c6473223b) *frame* ) SharedMemoryImageStream\_putframe push a new image into a server image stream channel. This function can only be called on a shared memory image stream created in server mode (options = IMAGESTREAM\_OPTIONS\_SERVER). The caller should create a frame structure with the frame number, the image size in pixels and a pointer to the image data (row major, tightly packed, RGB byte ordering). This call will copy the data pointed to by the buffer field, so the frame structure can be discarded after this call. Return codes: These are not technically errors, but they do provide some feedback on the current disposition of the image transport stream. IMAGESTREAM\_UNCONNECTED - no client has connected to this stream yet. IMAGESTREAM\_NO\_BUFFERAVAILABLE - the frame has not been queued because the client has not yet read previous frames. IMAGESTREAM\_NOERROR - the image frame has been queued up to be read by the client. Parameters \[in\]stream- the stream to push the image into \[in\]frame- the image to push into the stream ReturnsSharedMemoryImageError - the return code for the operation