PgCreateDriverRegion()

Create a region that's owned by the graphics driver

Synopsis:

PhRid_t PgCreateDriverRegion(
           PdOffscreenContext_t *osc,
           PhPoint_t   *origin,
           PhRect_t    *rect,
           PhRid_t     parent );

Arguments:

osc

A pointer to the PdOffscreenContext_t structure for the offscreen context. This argument must not be NULL.

origin

NULL, or a pointer to a PhPoint_t structure that specifies the origin of the region, relative to its parent. The default is (0,0) if this argument is NULL.

rect

NULL, or a pointer to a PhRect_t structure that specifies the region rectangle, relative to its origin. If this argument is NULL, the function uses a rectangle whose members are set to 0.

parent

The ID of the parent region, or -1 if you don't want to specify it.

Library:

ph

Description:

PgCreateDriverRegion() creates a region that's owned by the graphics driver and is sensitive to draw events.

The region parent defaults to the driver's input group's parent region. PhRegionOpen() defines all of the other default settings for the region. All draw events collected by the driver region are targeted at the specified offscreen context.

The driver region persists until you explicitly close it (which we don't recommend) or until the corresponding offscreen context is destroyed.

---

You must target this function at a device by calling PdSetTargetDevice().

---

A few notes:

• A single offscreen context is not usually associated with more than one driver region.
• The draw event translation isn't cleared when the drawstream is directed to the offscreen context.
• The driver region can be offset from its offscreen context using PdSetOffscreenTranslation().
• Client applications can manipulate a driver region by using its region ID. We don't generally recommend this.
• The driver region's handle (Ph_REGION_HANDLE) is reserved for use by the graphics driver. Don't change it.
• Since the region is owned by the graphics driver, all events collected by the region — including input events — are delivered to the graphics driver and not to the application that called this function.

Returns:

A nonnegative region id, or -1 if an error occurred.

Errors:

EFAULT

The function couldn't access the offscreen context.

EINVAL

The osc argument is NULL, or the call to PhRegionOpen() failed.

Classification:

Photon

See also:

PdOffscreenContext_t, PdSetOffscreenTranslation(), PdSetTargetDevice(), PhPoint_t, PhRect_t, PhRegionOpen()