EGD_GET_DATA(3)

💖 EGD_GET_DATA 💖

okay bestie, welcome to EGD_GET_DATA(3) — part of the EEGDEV library manual, and honestly? this one's kind of a big deal. it's the page about peeking at your buffered data 👀✨

---

🌸 NAME 🌸

egd_get_data — peek buffered data

---

✨ SYNOPSIS ✨

#include <eegdev.h>

ssize_t egd_get_available(struct eegdev* dev);
ssize_t egd_get_data(struct eegdev* dev, size_t ns, ...);

---

🎀 DESCRIPTION 🎀

so there's two functions here and they're besties fr fr.

egd_get_available() is the lil detective 🔍 — it tells you how many samples the device referenced by dev has buffered up and that nobody has read yet. like, "hey girl, there's this much data waiting for you."

egd_get_data() is the main character 💅 — it peeks the ns next samples from the buffered data that the device referenced by dev already acquired, and it fills the arrays you hand it in the variable list of arguments with all that obtained data. and here's the tea:

• if all the samples you asked for are already acquired? it returns immediately. instant. slay. ⚡
• if not? the call blocks until the requested data is available, the acquisition stops, or a problem happens. no cap.
• in those last two cases (acquisition stopped / problem), the data you actually read might be less than what you requested. so don't assume, okay? 🙈

the arrays you pass in the variable list of arguments get filled following the formats specified by a previous call to egd_acq_setup(3). specifically — and this part matters — the number of arrays you supply in the variable list of arguments, and their size, should be consistent with the number of arrays and strides specified by that call to egd_acq_setup(3). mismatch = not it.

---

👑 RETURN VALUE 👑

egd_get_available() returns the number of unread samples when it succeeds ✨. otherwise, -1 is returned and errno is set accordingly. periodt.

egd_get_data(), when it succeeds, returns the number of read samples — and yes, that can be less than the number you requested, so don't come for it 😭. otherwise, -1 is returned and errno is set accordingly.

---

💀 ERRORS 💀

both egd_get_available() and egd_get_data() will fail if:

• EINVAL — dev is NULL. bestie. it's nothing. it's literally nothing. 🙈
• ENOMEM — the internal ringbuffer of the device referenced by dev is full. it's giving overflow, we hate to see it.
• EAGAIN — the underlying hardware referenced by dev has encountered a loss of connection, maybe due some cable disconnected or a power switch set to off. yes the classic. check the cable. 🧚
• EIO — the underlying hardware referenced by dev has encountered a loss of synchronization for an unknown reason. mystery behavior, no explanation, iconic in the worst way 💀

---

🌈 NOTES 🌈

okay so important vibe check: the user has no obligation to make all the calls to egd_get_data() and egd_get_available() during the acquisition. nope! they can also perform some of them after the acquisition, which will correspond to getting the remaining buffered data. 🫶

for example (fr, this is a real scenario), it might happen that a user wants to wait for a certain external event to occur before stopping the acquisition. in that situation, the usual workflow would be:

1. start the acquisition
2. get regularly some data while scanning for the event to occur
3. when the event happens, the acquisition is immediately stopped

but!! at the moment of stopping the acquisition, there might still be some buffered data which could be important. so calling egd_get_available() after egd_stop(3) would then return the size of the remaining data that could be obtained with egd_get_data(). literally free real estate, don't leave it there 💖

---

🦋 EXAMPLE 🦋

#define NEEG   8
#define NTRI   1
#define NS     4

int ns_tot;
ssize_t ns_read;
float eegarr[NEEG*NS];
int32_t triarr[NTRI*NS];
struct grpconf grp[2];
unsigned int strides[2];

/* Assume that a device has been successfully opened, i.e. there
is a valid 'dev' variable of type struct eegdev* */

strides[0] = NEEG*sizeof(float);
strides[1] = NTRI*sizeof(int32_t);

grp[0].sensortype = egd_sensor_type("eeg");
grp[0].index = 0;
grp[0].iarray = 0;
grp[0].arr_offset = 0;
grp[0].nch = NEEG;
grp[0].datatype = EGD_FLOAT;
grp[1].sensortype = egd_sensor_type("trigger");
grp[1].index = 0;
grp[1].iarray = 1;
grp[1].arr_offset = 0;
grp[1].nch = NTRI;
grp[1].datatype = EGD_INT32;

/* Setup how to get the data */
egd_acq_setup(dev, 2, strides, 2, grp);

/* Start the acquisition.
From now, all incoming samples will be buffered */
egd_start(dev);
ns_tot = 0;

while (ns_tot < 1000) {
     /* Get the data */
     ns_read = egd_get_data(dev, NS, eegarr, triarr);
     if (ns_read < 0) {
          /* Handle failure */
     }
     ns_tot += ns_read;

     /* do something with the new data */
}

/* Stop the acquisition, i.e. no new data is buffered */
egd_stop(dev);

---

💜 SEE ALSO 💜

egd_acq_setup(3), egd_start(3), egd_stop(3)

---

and that's the page bestie!! 🌟 this one came from EPFL, dated 2010, and it lives on as EGD_GET_DATA(3) in the EEGDEV library manual. go peek at that buffer, you got this 🎀✨💖