## On this page

  

 

 # shared\_memory\_image\_client.h File Reference

 Last update: 16.07.2025 

C API for using the EnSight grpc shared memory image transport API. [More...](#details)

`#include <stdint.h>`  


[Go to the source code of this file.](shared__memory__image__client_8h_source.html)

## <a id="nested-classes" name="nested-classes"></a>Classes

struct [\_SharedMemoryFrame](struct___shared_memory_frame.html) ## <a id="define-members" name="define-members"></a>Macros

\#define [IMAGESTREAM\_API\_VERSION](#a64df229b0ac6942d9bdee4b94b2c096a) "1.0" \#define [IMAGESTREAM\_UNCONNECTED](#a2cc13f7eda736fddce876cf5cae2c502) 4 \#define [IMAGESTREAM\_RECONNECTING](#aa17e85c9001e414b9ac1db640884b944) 3 \#define [IMAGESTREAM\_NO\_FRAMEAVAILABLE](#a7a7491d1019b67d55ac6488c0e3cb637) 2 \#define [IMAGESTREAM\_NO\_BUFFERAVAILABLE](#a78414d594aa9bb3f9bcea84c768d2826) 1 \#define [IMAGESTREAM\_NOERROR](#af995dd87ffd7dd178eef1d343f7b72bf) 0 \#define [IMAGESTREAM\_BAD\_ARGS](#ac2b3e8a36182f38dab1c5fd7a700a0c6) -1 \#define [IMAGESTREAM\_NOT\_LOCKED](#ab7873d9185a495020022f80c238142bc) -2 \#define [IMAGESTREAM\_BAD\_FILE\_SIZE](#a54a45d2f039e6275c28249eedfa2515d) -3 \#define [IMAGESTREAM\_UNABLE\_TO\_OPEN\_FILE](#a5b68da171a139f688d317320d0a4eb3e) -4 \#define [IMAGESTREAM\_UNABLE\_TO\_MAP\_FILE](#ac7eb344cf60975382720f71182dab490) -5 \#define [IMAGESTREAM\_MEMORY\_ALLOC\_ERROR](#ae37af5c9dcf1d89b30b82ca4be840cfe) -6 \#define [IMAGESTREAM\_THREAD\_CREATE\_ERROR](#ac0d310d75b0c3ff53d524a0a5fe25b6f) -7 \#define [IMAGESTREAM\_IS\_SERVER](#ac914cc76952081d1ccc7c520e12770b1) -8 \#define [IMAGESTREAM\_IS\_NOTSERVER](#aff57dd9d671a32995d562d68fcfa5fff) -9 \#define [IMAGESTREAM\_FRAME\_TOO\_LARGE](#ae5bdc8c10b2aa9db85d0955c99cba2c6) -10 \#define [IMAGESTREAM\_LOCKED](#a8389f19c29b726a2bed3c5831d1fb267) -11 \#define [IMAGESTREAM\_OPTIONS\_NONE](#a7fbe522f7a46875a755f07c8ff69e2df) 0x00000000 \#define [IMAGESTREAM\_OPTIONS\_FLIPVERTICAL](#a536935e36e51aade42c2a49f8ecd7ae1) 0x00000100 ## <a id="typedef-members" name="typedef-members"></a>Typedefs

typedef int [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) common error codes see the non-hex, non-string IMAGESTREAM macros   
 typedef struct \_SharedMemoryImageStream \* [SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749) image transport stream pointer   
 typedef struct [\_SharedMemoryFrame](struct___shared_memory_frame.html) \* [SharedMemoryFrame](#a995c49496fcc1a41fb2d104c6473223b) A reference to a frame of imagery. Note it does not own the buffer pointer.   
 ## <a id="func-members" name="func-members"></a>Functions

[SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) [SharedMemoryImageStream\_create](#a03ba052ae823b3e39fef153db8f03ea2) (const char \*filename, uint32\_t options, [SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749) \*stream) SharedMemoryImageStream\_create create a stream client instance.   
 [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) [SharedMemoryImageStream\_lock](#afefb8f5297147640b46d1f9eb1e77c9e) ([SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749) stream, [SharedMemoryFrame](#a995c49496fcc1a41fb2d104c6473223b) \*frame) SharedMemoryImageStream\_lock get a frame of pixels from the server.   
 [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) [SharedMemoryImageStream\_unlock](#ac885e449551afd5fb5a7f19c5ec785a6) ([SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749) stream) SharedMemoryImageStream\_unlock release a frame obtained by SharedMemoryImageStream\_lock.   
 [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) [SharedMemoryImageStream\_destroy](#a4ea47b6bda387b71ed5f91db329eff65) ([SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749) stream) SharedMemoryImageStream\_destroy destroy a stream interface, releasing its resources.   
 const char \* [SharedMemoryImageStream\_errorstring](#a16abb961cf38273321e81cc64d71fad7) ([SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) err) SharedMemoryImageStream\_errorstring convert an error code into a human string.   
 <a id="details" name="details"></a>## Detailed Description

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

Version1.0This 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()](#a03ba052ae823b3e39fef153db8f03ea2 "SharedMemoryImageStream_create create a stream client instance.") to connect to the server. [SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749) stream;
    
    [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) err;
    
    err = [SharedMemoryImageStream\_create](#a03ba052ae823b3e39fef153db8f03ea2)("shared\_memory\_file", 
    
     [IMAGESTREAM\_OPTIONS\_NONE](#a7fbe522f7a46875a755f07c8ff69e2df), &amp;stream);
    
    if (err &lt; [IMAGESTREAM\_NOERROR](#af995dd87ffd7dd178eef1d343f7b72bf)) &lt;handle error&gt;
    
    [SharedMemoryImageStream\_create](#a03ba052ae823b3e39fef153db8f03ea2)
    
    SharedMemoryImageError SharedMemoryImageStream_create(const char *filename, uint32_t options, SharedMemoryImageStream *stream)
    
    SharedMemoryImageStream_create create a stream client instance.
    
    
    
    [SharedMemoryImageError](#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.html#l00109)
    
    
    
    [IMAGESTREAM\_OPTIONS\_NONE](#a7fbe522f7a46875a755f07c8ff69e2df)
    
    \#define IMAGESTREAM_OPTIONS_NONE
    
    **Definition** [shared\_memory\_image\_client.h:103](shared__memory__image__client_8h_source.html#l00103)
    
    
    
    [SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749)
    
    struct _SharedMemoryImageStream * SharedMemoryImageStream
    
    image transport stream pointer
    
    **Definition** [shared\_memory\_image\_client.h:111](shared__memory__image__client_8h_source.html#l00111)
    
    
    
    [IMAGESTREAM\_NOERROR](#af995dd87ffd7dd178eef1d343f7b72bf)
    
    \#define IMAGESTREAM_NOERROR
    
    **Definition** [shared\_memory\_image\_client.h:88](shared__memory__image__client_8h_source.html#l00088)
6. Periodically, the client checks for a new image: [SharedMemoryFrame](struct___shared_memory_frame.html) frame;
    
    if ([IMAGESTREAM\_NOERROR](#af995dd87ffd7dd178eef1d343f7b72bf) == [SharedMemoryImageStream\_lock](#afefb8f5297147640b46d1f9eb1e77c9e)(stream, &amp;frame)) {
    
     &lt;work on the pixels returned in 'frame'&gt;
    
     [SharedMemoryImageStream\_unlock](#ac885e449551afd5fb5a7f19c5ec785a6)(stream);
    
    }
    
    [SharedMemoryImageStream\_unlock](#ac885e449551afd5fb5a7f19c5ec785a6)
    
    SharedMemoryImageError SharedMemoryImageStream_unlock(SharedMemoryImageStream stream)
    
    SharedMemoryImageStream_unlock release a frame obtained by SharedMemoryImageStream_lock.
    
    
    
    [SharedMemoryImageStream\_lock](#afefb8f5297147640b46d1f9eb1e77c9e)
    
    SharedMemoryImageError SharedMemoryImageStream_lock(SharedMemoryImageStream stream, SharedMemoryFrame *frame)
    
    SharedMemoryImageStream_lock get a frame of pixels from the server.
    
    
    
    [\_SharedMemoryFrame](struct___shared_memory_frame.html)
    
    **Definition** [shared\_memory\_image\_client.h:115](shared__memory__image__client_8h_source.html#l00115)
    
    
    
    
    
     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](#a0496a9a3db499fa9145fe97d2e6dae9a) err = [SharedMemoryImageStream\_destroy](#a4ea47b6bda387b71ed5f91db329eff65)(stream);
    
    [SharedMemoryImageStream\_destroy](#a4ea47b6bda387b71ed5f91db329eff65)
    
    SharedMemoryImageError SharedMemoryImageStream_destroy(SharedMemoryImageStream stream)
    
    SharedMemoryImageStream_destroy destroy a stream interface, releasing its resources.

Definition in file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).



## Macro Definition Documentation

<a id="a64df229b0ac6942d9bdee4b94b2c096a" name="a64df229b0ac6942d9bdee4b94b2c096a"></a>## [◆ ](#a64df229b0ac6942d9bdee4b94b2c096a)IMAGESTREAM\_API\_VERSION

 \#define IMAGESTREAM\_API\_VERSION "1.0"

The current API version

Definition at line [81](shared__memory__image__client_8h_source.html#l00081) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="ac2b3e8a36182f38dab1c5fd7a700a0c6" name="ac2b3e8a36182f38dab1c5fd7a700a0c6"></a>## [◆ ](#ac2b3e8a36182f38dab1c5fd7a700a0c6)IMAGESTREAM\_BAD\_ARGS

 \#define IMAGESTREAM\_BAD\_ARGS -1

one of the input parameters is invalid

Definition at line [90](shared__memory__image__client_8h_source.html#l00090) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="a54a45d2f039e6275c28249eedfa2515d" name="a54a45d2f039e6275c28249eedfa2515d"></a>## [◆ ](#a54a45d2f039e6275c28249eedfa2515d)IMAGESTREAM\_BAD\_FILE\_SIZE

 \#define IMAGESTREAM\_BAD\_FILE\_SIZE -3

the shared memory file is too small (&lt;10MB) or non-existant

Definition at line [92](shared__memory__image__client_8h_source.html#l00092) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="ae5bdc8c10b2aa9db85d0955c99cba2c6" name="ae5bdc8c10b2aa9db85d0955c99cba2c6"></a>## [◆ ](#ae5bdc8c10b2aa9db85d0955c99cba2c6)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](shared__memory__image__client_8h_source.html#l00099) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="aff57dd9d671a32995d562d68fcfa5fff" name="aff57dd9d671a32995d562d68fcfa5fff"></a>## [◆ ](#aff57dd9d671a32995d562d68fcfa5fff)IMAGESTREAM\_IS\_NOTSERVER

 \#define IMAGESTREAM\_IS\_NOTSERVER -9

the call is not valid for shared memory client to make

Definition at line [98](shared__memory__image__client_8h_source.html#l00098) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="ac914cc76952081d1ccc7c520e12770b1" name="ac914cc76952081d1ccc7c520e12770b1"></a>## [◆ ](#ac914cc76952081d1ccc7c520e12770b1)IMAGESTREAM\_IS\_SERVER

 \#define IMAGESTREAM\_IS\_SERVER -8

the call is not valid for shared memory server to make

Definition at line [97](shared__memory__image__client_8h_source.html#l00097) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="a8389f19c29b726a2bed3c5831d1fb267" name="a8389f19c29b726a2bed3c5831d1fb267"></a>## [◆ ](#a8389f19c29b726a2bed3c5831d1fb267)IMAGESTREAM\_LOCKED

 \#define IMAGESTREAM\_LOCKED -11

this call is not legal until the stream has been unlocked

Definition at line [100](shared__memory__image__client_8h_source.html#l00100) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="ae37af5c9dcf1d89b30b82ca4be840cfe" name="ae37af5c9dcf1d89b30b82ca4be840cfe"></a>## [◆ ](#ae37af5c9dcf1d89b30b82ca4be840cfe)IMAGESTREAM\_MEMORY\_ALLOC\_ERROR

 \#define IMAGESTREAM\_MEMORY\_ALLOC\_ERROR -6

insufficient system memory for internal object allocation

Definition at line [95](shared__memory__image__client_8h_source.html#l00095) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="a78414d594aa9bb3f9bcea84c768d2826" name="a78414d594aa9bb3f9bcea84c768d2826"></a>## [◆ ](#a78414d594aa9bb3f9bcea84c768d2826)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](shared__memory__image__client_8h_source.html#l00087) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="a7a7491d1019b67d55ac6488c0e3cb637" name="a7a7491d1019b67d55ac6488c0e3cb637"></a>## [◆ ](#a7a7491d1019b67d55ac6488c0e3cb637)IMAGESTREAM\_NO\_FRAMEAVAILABLE

 \#define IMAGESTREAM\_NO\_FRAMEAVAILABLE 2

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

Definition at line [86](shared__memory__image__client_8h_source.html#l00086) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="af995dd87ffd7dd178eef1d343f7b72bf" name="af995dd87ffd7dd178eef1d343f7b72bf"></a>## [◆ ](#af995dd87ffd7dd178eef1d343f7b72bf)IMAGESTREAM\_NOERROR

 \#define IMAGESTREAM\_NOERROR 0

Operation successful

Definition at line [88](shared__memory__image__client_8h_source.html#l00088) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="ab7873d9185a495020022f80c238142bc" name="ab7873d9185a495020022f80c238142bc"></a>## [◆ ](#ab7873d9185a495020022f80c238142bc)IMAGESTREAM\_NOT\_LOCKED

 \#define IMAGESTREAM\_NOT\_LOCKED -2

an attempt was made to unlock without it having been locked

Definition at line [91](shared__memory__image__client_8h_source.html#l00091) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="a536935e36e51aade42c2a49f8ecd7ae1" name="a536935e36e51aade42c2a49f8ecd7ae1"></a>## [◆ ](#a536935e36e51aade42c2a49f8ecd7ae1)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](shared__memory__image__client_8h_source.html#l00105) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="a7fbe522f7a46875a755f07c8ff69e2df" name="a7fbe522f7a46875a755f07c8ff69e2df"></a>## [◆ ](#a7fbe522f7a46875a755f07c8ff69e2df)IMAGESTREAM\_OPTIONS\_NONE

 \#define IMAGESTREAM\_OPTIONS\_NONE 0x00000000

the default options for a client stream

Definition at line [103](shared__memory__image__client_8h_source.html#l00103) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="aa17e85c9001e414b9ac1db640884b944" name="aa17e85c9001e414b9ac1db640884b944"></a>## [◆ ](#aa17e85c9001e414b9ac1db640884b944)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](shared__memory__image__client_8h_source.html#l00085) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="ac0d310d75b0c3ff53d524a0a5fe25b6f" name="ac0d310d75b0c3ff53d524a0a5fe25b6f"></a>## [◆ ](#ac0d310d75b0c3ff53d524a0a5fe25b6f)IMAGESTREAM\_THREAD\_CREATE\_ERROR

 \#define IMAGESTREAM\_THREAD\_CREATE\_ERROR -7

unable to create background processing threads

Definition at line [96](shared__memory__image__client_8h_source.html#l00096) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="ac7eb344cf60975382720f71182dab490" name="ac7eb344cf60975382720f71182dab490"></a>## [◆ ](#ac7eb344cf60975382720f71182dab490)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](shared__memory__image__client_8h_source.html#l00094) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="a5b68da171a139f688d317320d0a4eb3e" name="a5b68da171a139f688d317320d0a4eb3e"></a>## [◆ ](#a5b68da171a139f688d317320d0a4eb3e)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](shared__memory__image__client_8h_source.html#l00093) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="a2cc13f7eda736fddce876cf5cae2c502" name="a2cc13f7eda736fddce876cf5cae2c502"></a>## [◆ ](#a2cc13f7eda736fddce876cf5cae2c502)IMAGESTREAM\_UNCONNECTED

 \#define IMAGESTREAM\_UNCONNECTED 4

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

Definition at line [84](shared__memory__image__client_8h_source.html#l00084) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





## Typedef Documentation

<a id="a995c49496fcc1a41fb2d104c6473223b" name="a995c49496fcc1a41fb2d104c6473223b"></a>## [◆ ](#a995c49496fcc1a41fb2d104c6473223b)SharedMemoryFrame

 typedef struct [\_SharedMemoryFrame](struct___shared_memory_frame.html) \* [SharedMemoryFrame](#a995c49496fcc1a41fb2d104c6473223b)

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

Structure representing a frame of imagery in sequence





<a id="a0496a9a3db499fa9145fe97d2e6dae9a" name="a0496a9a3db499fa9145fe97d2e6dae9a"></a>## [◆ ](#a0496a9a3db499fa9145fe97d2e6dae9a)SharedMemoryImageError

 typedef int [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a)

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

Definition at line [109](shared__memory__image__client_8h_source.html#l00109) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





<a id="af5b8eb2ae90823f10e9a17698ea80749" name="af5b8eb2ae90823f10e9a17698ea80749"></a>## [◆ ](#af5b8eb2ae90823f10e9a17698ea80749)SharedMemoryImageStream

 typedef struct \_SharedMemoryImageStream\* [SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749)

image transport stream pointer

Definition at line [111](shared__memory__image__client_8h_source.html#l00111) of file [shared\_memory\_image\_client.h](shared__memory__image__client_8h_source.html).





## Function Documentation

<a id="a03ba052ae823b3e39fef153db8f03ea2" name="a03ba052ae823b3e39fef153db8f03ea2"></a>## [◆ ](#a03ba052ae823b3e39fef153db8f03ea2)SharedMemoryImageStream\_create()

 [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) SharedMemoryImageStream\_create  ( const char \* *filename*,    uint32\_t *options*,    [SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749) \* *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 &gt;=0, this pointer will be returned. ReturnsSharedMemoryImageError - the error code for this call. 



<a id="a4ea47b6bda387b71ed5f91db329eff65" name="a4ea47b6bda387b71ed5f91db329eff65"></a>## [◆ ](#a4ea47b6bda387b71ed5f91db329eff65)SharedMemoryImageStream\_destroy()

 [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) SharedMemoryImageStream\_destroy  ( [SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749) *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 ReturnsSharedMemoryImageError - error code for the operation 



<a id="a16abb961cf38273321e81cc64d71fad7" name="a16abb961cf38273321e81cc64d71fad7"></a>## [◆ ](#a16abb961cf38273321e81cc64d71fad7)SharedMemoryImageStream\_errorstring()

 const char \* SharedMemoryImageStream\_errorstring  ( [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) *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 Returnsconst char \* - The string describing the error (utf8 encoding) 



<a id="afefb8f5297147640b46d1f9eb1e77c9e" name="afefb8f5297147640b46d1f9eb1e77c9e"></a>## [◆ ](#afefb8f5297147640b46d1f9eb1e77c9e)SharedMemoryImageStream\_lock()

 [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) SharedMemoryImageStream\_lock  ( [SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749) *stream*,    [SharedMemoryFrame](#a995c49496fcc1a41fb2d104c6473223b) \* *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()](#ac885e449551afd5fb5a7f19c5ec785a6 "SharedMemoryImageStream_unlock release a frame obtained by SharedMemoryImageStream_lock.") is called. If the function returns IMAGESTREAM\_NO\_FRAMEAVAILABLE, no new imagery is available from the server and [SharedMemoryImageStream\_unlock()](#ac885e449551afd5fb5a7f19c5ec785a6 "SharedMemoryImageStream_unlock release a frame obtained by SharedMemoryImageStream_lock.") 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) ReturnsSharedMemoryImageError - the error code for the operation. 



<a id="ac885e449551afd5fb5a7f19c5ec785a6" name="ac885e449551afd5fb5a7f19c5ec785a6"></a>## [◆ ](#ac885e449551afd5fb5a7f19c5ec785a6)SharedMemoryImageStream\_unlock()

 [SharedMemoryImageError](#a0496a9a3db499fa9145fe97d2e6dae9a) SharedMemoryImageStream\_unlock  ( [SharedMemoryImageStream](#af5b8eb2ae90823f10e9a17698ea80749) *stream*) 

SharedMemoryImageStream\_unlock release a frame obtained by SharedMemoryImageStream\_lock.

If [SharedMemoryImageStream\_lock()](#afefb8f5297147640b46d1f9eb1e77c9e "SharedMemoryImageStream_lock get a frame of pixels from the server.") 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 ReturnsSharedMemoryImageError - error code for the operation