PhRegionInfo()

Retrieve information about a region

Synopsis:

int PhRegionInfo( PhRid_t rid,
                  PhRegion_t *region,
                  PhRect_t rects[],
                  unsigned nrect,
                  void *data,
                  unsigned data_len );

Arguments:

rid

The region to query.

region

A PhRegion_t structure that the function fills in with region information.

rects

An array of PhRect_t structures that the function fills in with region rectangle information.

nrect

The length of the array pointed to by rects. See the note below.

data

If the queried region has data attached to it, up to data_len bytes is copied into this member. This data may consist of smaller blocks of data of different types, each preceded by a PhRegionDataHdr_t structure. To find a specific type of data in the region's data, call PhRegionDataFindType().

data_len

The maximum number of region data bytes to copy into data.

Library:

ph

Description:

This function returns information about the region identified by rid. On completion, the PhRegion_t structure pointed to by region and the PhRect_t structures pointed to by rects contain a description of the region.

---

This function is similar to PhRegionQuery(), but it supports multiple rectangles. In a future release, it may be possible to create regions with multiple rectangles. If you want your code to be prepared to handle such regions correctly, you may consider using PhRegionInfo() instead of PhRegionQuery(). The number of rectangles in the region is returned in region->num_rects. If that number is greater than nrect, and nrect is greater than zero, then rects[0] is set to the region's bounding box and the rest of rects remain unchanged.

---

Returns:

0

Success.

-1

An error occurred.

Examples:

The following example gets information about the device region:

#define NRECTS 10
PhRegion_t region; PhRect_t rects[ NRECTS ];

if( !PhRegionInfo( Ph_DEV_RID, &region,
                    rects, NRECTS, NULL, 0 ) ) {
  printf( "Sensitive to: %.8x Opaque to: %.8x\n",
    region.events_sense, region.events_opaque );
  if ( region.num_rects > NRECTS )
    printf( "%d rectangles, bounding box: {(%d,%d),(%d,%d)}\n",
       region.num_rects,
       region.origin.x + rect[0].ul.x,
       region.origin.y + rect[0].ul.y,
       region.origin.x + rect[0].lr.x,
       region.origin.y + rect[0].lr.y );
    else {
       int i;
       printf( "%d rectangles:\n", region.num_rects );
       for ( i=0; i<region.num_rects; ++i )
          printf( " {(%d,%d),(%d,%d)}\n",
             region.origin.x + rect[i].ul.x,
             region.origin.y + rect[i].ul.y,
             region.origin.x + rect[i].lr.x,
             region.origin.y + rect[i].lr.y );
    }
}

Classification:

Photon

See also:

PhRect_t, PhRegion_t, PhRegionChange(), PhRegionOpen()

Regions chapter of the Photon Programmer's Guide