NAME

INQUIRE LIGHT SOURCE REPRESENTATION - inquire for light source representation for specified workstation

SYNOPSIS

C Syntax

void

pinq_light_src_rep ( ws, index, type, error_ind, rep )

Pint                 ws;           workstation identifier
Pint                 index;        light source index
Pinq_type            type;         type of returned value
Pint                 * error_ind;  OUT error indicator
Plight_src_bundle    * rep;        OUT light source representation

FORTRAN Syntax

SUBROUTINE pqlsr ( WKID, ILS, ITYPE, MLDR, ERRIND, LSTYPE, LDR, DATREC )

INTEGER             WKID               workstation identifier
INTEGER             ILS                index into the light source list
INTEGER             ITYPE              type of returned values (PSET, PREALI )
INTEGER             MLDR               dimension of data record array
INTEGER             ERRIND             OUT error indicator
INTEGER             LSTYPE             OUT light source type
INTEGER             LDR                OUT actual size of the data record
CHARACTER* 80       DATREC(LDR)        OUT data record

Required PHIGS Operating States

(PHOP, WSOP, * ,* )

DESCRIPTION

Purpose

INQUIRE LIGHT SOURCE REPRESENTATION inquires for a light source representation for a given workstation.

This is a SunPHIGS Extension function based on PHIGS PLUS and is not part of the PHIGS standard.

C Input Parameters

ws

The workstation identifier.

index

The light source index.

type

An enumerated value specifying whether the values to be returned are those originally specified by the application (PINQ_SET), or those resulting after PHIGS mapped them to ones available on the workstation (PINQ_REALIZED).

A Pinq_type structure is defined as:

typedef enum {

PINQ_SET,

PINQ_REALIZED

} Pinq_type;

C Output Parameters

error_ind

A pointer to the location to store the error number of any error detected by this function.

rep

A pointer to the location in which to return the light source representation. The Plight_src_bundle data structure contains values needed to define the specified type of light source representation. Plight_src_bundle is defined as:

typedef struct {

Pint            type;           /* light source type * /
Plight_src_rec rec;             /* light source data record * /

} Plight_src_bundle;

Plight_src_rec is defined as:

typedef union {

Pamb_light_src_rec

ambient;

Pdir_light_src_rec

directional;

Ppos_light_src_rec

positional;

Pspot_light_src_rec

spot;

} Plight_src_rec;

Pamb_light_src_rec is defined as:

typedef struct {

Pgcolr colr;

/* light source colour * /

} Pamb_light_src_rec;

Pgcolr is defined as:

typedef struct {

Pinttype;

/* indirect, RGB, CIE, HSV, HLS * /

union {

Pint

ind;

/* index in workstation colour bundle table * /

struct {

Pfloat

delta_x; /* red, hue, and so on * /

Pfloat

delta_y; /* green, saturation, lightness, and so on * /

Pfloat

delta_z; /* blue, value, saturation, and so on * /

} general;

} val;

} Pgcolr;

Pdir_light_src_rec is defined as:

typedef struct {

Pgcolr colr;

/* light source colour * /

Pvec3

dir;

/* light source direction * /

} Pdir_light_src_rec;

Pvec3 is defined as:

typedef struct {

Pfloat   delta_x;   /* x magnitude * /
Pfloat   delta_y;   /* y magnitude * /
Pfloat   delta_z;   /* z magnitude * /

} Pvec3;

Ppos_light_src_rec is defined as:

typedef struct {

Pgcolr    colr;     /* light source colour * /
Ppoint3   pos;      /* light source position * /
Pfloat     coef[2];  /* attenuation coefficients * /

} Ppos_light_src_rec;

Ppoint3 is defined as:

typedef struct {

Pfloat   x;      /* x coordinate * /
Pfloat   y;      /* y coordinate * /
Pfloat   z;      /* z coordinate * /

} Ppoint3;

Pspot_light_src_rec is defined as:

typedef struct {

Pgcolr    colr;     /* light source colour * /
Ppoint3   pos;      /* light source position * /
Pvec3     dir;      /* light source direction * /
Pfloat     exp;      /* concentration exponent * /
Pfloat     coef[2];  /* attenuation coefficients * /
Pfloat     angle;    /* half-cone spread angle * /

} Pspot_light_src_rec;

FORTRAN Input Parameters

All of the following data types are predefined in phigs77.h.

WKID

The identifier of the workstation for which the light source indices list is being inquired.

ILS

An index into the light source table of the workstation state list.

ITYPE

An enumerated value specifying whether the values to be returned are those originally specified by the application (Set), or those resulting after PHIGS mapped them to ones available on the workstation (Realized). Valid values are:

0   PSET      Set
1   PREALI    Realized

MLDR

The dimension of the data record array, DATREC.

FORTRAN Output Parameters

ERRIND

The error number of any error detected by this function.

LSTYPE

The light source type.

LDR

The actual size, in elements, returned in the data record.

DATREC(LDR)

The data record that must be unpacked by UNPACK DATA RECORD. The contents depend on the light source type. See SET LIGHT SOURCE REPRESENTATION for a description of its contents.

Execution

If the specified light source index is not present in the light source table on the workstation, and the specified type of returned value is Realized, the representation for light source index one is returned.

If the inquired information is not available, then the values returned in the output parameters are undefined, and the error indicator is set to one of the following error numbers to indicate the reason for nonavailability.

Since this is an inquiry function, ERROR HANDLING is not invoked when an error is detected by this function.

ERRORS

003

Ignoring function, function requires state (PHOP, WSOP, * ,* )

054

Ignoring function, the specified workstation is not open

059

Ignoring function, the specified workstation does not have output capability

101

Ignoring function, the specified representation has not been defined

614

Ignoring function, the light source index is less than one

SEE ALSO

SET LIGHT SOURCE STATE (3PP)

SET LIGHT SOURCE REPRESENTATION (3PP)

INQUIRE LIST OF LIGHT SOURCE INDICES (3PP)

INQUIRE LIGHT SOURCE FACILITIES (3PP)

INQUIRE PREDEFINED LIGHT SOURCE REPRESENTATION (3PP)