PgSetLayerArg()

Configure a layer argument

Synopsis:

int PgSetLayerArg( int layer,
                   int arg,
                   void *data,
                   int data_len );

Arguments:

layer

The layer index, which must be 0 or greater.

arg

One of:

• Pg_LAYER_ARG_ACTIVE
• Pg_LAYER_ARG_FORMAT_INDEX
• Pg_LAYER_ARG_DST_VIEWPORT
• Pg_LAYER_ARG_SRC_VIEWPORT
• Pg_LAYER_ARG_BRIGHTNESS
• Pg_LAYER_ARG_SATURATION
• Pg_LAYER_ARG_CONTRAST
• Pg_LAYER_ARG_CHROMA
• Pg_LAYER_ARG_ALPHA
• Pg_LAYER_ARG_EDGE_MODE
• Pg_LAYER_ARG_FILTER_MODE
• Pg_LAYER_ARG_LIST_BEGIN
• Pg_LAYER_ARG_LIST_END

For more information, see “Layer arguments,” below.

data

A pointer to an argument-dependent value.

data_len

The size of the data.

Library:

ph

Description:

PgSetLayerArg() configures the specified layer argument. This function replaces the existing value of the argument with the new value. It doesn't free dynamically allocated data. If this function fails, then the value of the argument is undefined.

---

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

---

You can change layer arguments only after a call to PgSetLayerArg() with an argument of Pg_LAYER_ARG_LIST_BEGIN, and before another call with an argument of Pg_LAYER_ARG_LIST_END. For example:

int fmt_idx = 5;
PgSetLayerArg( layer, Pg_LAYER_ARG_LIST_BEGIN, NULL, 0 );
PgSetLayerArg( layer, Pg_LAYER_ARG_FORMAT_INDEX,
               &fmt_idx, sizeof(int) );
PgSetLayerSurface( layer, 0, osc0 );
PgSetLayerSurface( layer, 1, osc1 );
PgSetLayerSurface( layer, 2, osc2 );
PgSetLayerArg( layer, Pg_LAYER_ARG_BRIGHTNESS, ... );
PgSetLayerArg( layer, ... );
...
PgSetLayerArg( layer, Pg_LAYER_ARG_LIST_END, NULL, 0 );

Layer arguments

The arguments for a layer are as follows:

Pg_LAYER_ARG_ACTIVE

Whether the layer is active (shown) or hidden.

Type	Range	Default
int	{0, !0}	0 if the layer can be hidden, or 1 if it can't be hidden

Pg_LAYER_ARG_FORMAT_INDEX

The layer format, by index. The index corresponds to the format_index passed to PgGetLayerCaps().

Type	Range	Default
int	≥ 0	Undefined

Pg_LAYER_ARG_DST_VIEWPORT

The rectangle on the screen where the source data is displayed.

Type	Default
PhArea_t	The maximum area allowed by the driver

Pg_LAYER_ARG_SRC_VIEWPORT

The rectangle within the source data that's displayed by the layer.

Type	Default
PhArea_t	The same as the destination viewport, or the maximum area allowed by the driver, if smaller

Pg_LAYER_ARG_BRIGHTNESS

The brightness level.

Type	Range	Default
int	-128 to 127	0

Pg_LAYER_ARG_SATURATION

The saturation level.

Type	Range	Default
int	-128 to 127	0

Pg_LAYER_ARG_CONTRAST

The contrast level.

Type	Range	Default
int	-128 to 127	0

Pg_LAYER_ARG_CHROMA

Chroma information, stored in a PgChroma_t structure:

typedef struct _Pg_chroma {
        unsigned int     color;
        unsigned long    op;
        } PgChroma_t;
  

The members include:

• color — a 32-bit color.
• op — the chroma operation; one of the Pg_CHROMA_* operations described for PgSetChroma().

Type	Default
PgChroma_t	op = 0, color = N/A

Pg_LAYER_ARG_ALPHA

Alpha blending for the layer, stored in a PgLayerAlpha_t structure:

typedef struct {
    unsigned int op;
    unsigned int salpha;
    unsigned int dalpha;
} PgLayerAlpha_t;
  

The members include:

• op — a bitwise OR of Pg_LAYER_ALPHA_* and Pg_LAYER_BLEND_* values, as described for PgGetLayerCaps().
• salpha — the source alpha value (0 to 0xFF).
• dalpha — the destination alpha value (0 to 0xFF).

The salpha and dalpha members are ignored unless the op specifies that they should be used.

Type	Default
PgLayerAlpha_t	op = 0

Pg_LAYER_ARG_EDGE_MODE

How to behave if the source viewport is larger than the extent of the source data.

Type	Range	Default
unsigned int	Pg_LAYER_EDGE_WRAP, Pg_LAYER_EDGE_CLAMP, or 0	0

Pg_LAYER_ARG_FILTER_MODE

Enable or disable viewport filtering.

Type	Range	Default
unsigned int	Pg_LAYER_FILTER or 0	0

Pg_LAYER_ARG_LIST_BEGIN, Pg_LAYER_ARG_LIST_END

Bracket a set of calls to PgSetLayerArg() or PgSetLayerSurface() with these to queue up register updates.

Type	Range	Default
None	N/A	N/A

Returns:

0

Success.

-1

An error occurred (errno is set).

Errors:

EBUSY

The layer is locked by another application.

EINVAL

The specified layer doesn't exist, the layer doesn't support the given argument, or the data specified for the argument is invalid.

EOPNOTSUPP

The layer doesn't support this argument.

Examples:

Classification:

Photon

See also:

PdSetTargetDevice(), PgGetLayerCaps(), PgSetChroma(), PgSetLayerSurface(), PhArea_t

“Layers” in the Raw Drawing and Animation chapter of the Photon Programmer's Guide