PhEventEmitmx()

Emit an event when the event-specific data isn't contiguous in memory

Synopsis:

int PhEventEmitmx( PhEvent_t const *event,
                   PhRect_t const *rects,
                   int mxparts,
                   iov_t *mx );

Description:

This function provides an alternative to PhEventEmit(). You'll find it useful when the event-specific data isn't contiguous in memory.

PhEventEmitmx() is used internally by PgFlush() (which emits a draw event) to avoid copying large amounts of variable-length data, such as bitmaps, into the draw buffer. Instead of copying the data, the library builds mx entries to that data and then passes the mx entry list to PhEventEmitmx(), which in turn emits the draw event.

The mx argument points to an array of mx entries, and mxparts contains the number of mx entries pointed to by mx. You should leave the first 3 mx entries blank; these will be filled in by the PhEventEmitmx() call. You're free to use the remaining entries to build a description of the data to be attached to the event.

The event argument points to the standard event data structure and rects points to an array of rectangles. For the restrictions that apply to rects and to the attached data, see PhEventEmit().

Returns:

0

Successful completion.

-1

An error occurred, or no further events are pending. Check the value of errno:

• If errno is ENOMSG, Photon had no messages enqueued to your application at the time you emitted the event.
• If errno isn't ENOMSG, an error occurred.

These return codes are useful for applications that spend most of their time emitting events and want to retrieve an event only if there's one pending for them.

Examples:

The following example emits a pointer press event. (A PhEventEmit() call would be just as efficient and slightly more convenient...)

#include <stdio.h>
#include <time.h>
#include <Ph.h>

main( int argc, char *argv[] )
{
     PhEvent_t event;
     PhRect_t rect;
     PhPointerEvent_t ptr_event;
     struct _mxfer_entry mx[4];

     if( NULL == PhAttach( NULL, NULL ) ) {
     
          fprintf( stderr,
                 "Could not attach a Photon channel.\n");
          exit( EXIT_FAILURE );
     }
     event.type = Ph_EV_BUT_PRESS;
     event.subtype = 0;
     event.src.rid = Ph_DEV_RID;
     event.flags = 0;
     event.num_rects = 1;
     event.data_len = sizeof( ptr_event );
     rect.ul.x = rect.lr.x = 100;
     rect.ul.y = rect.lr.y = 200;
     ptr_event.flags = 0;
     ptr_event.buttons = Ph_BUTTON_SELECT;
     _setmx( &mx[3], &ptr_event, sizeof( ptr_event ) );
     PhEventEmitmx( &event, &rect, 4, mx );
}

Classification:

Photon

See also:

PgFlush(), PhEventEmit()

Sendmx(), _setmx() (in the C Library Reference)