NAME

INQUIRE PREDEFINED COLOUR MAPPING REPRESENTATION - inquire for a predefined colour mapping representation for the specified workstation type

SYNOPSIS

C Syntax

void

pinq_pred_colr_map_rep ( type, index, store, error_ind, map_method, map_data )

Pint               type;            workstation type
Pint               index;           predefined index
Pstore             store;           handle to store data
Pint               * error_ind;     OUT error indicator
Pint               * map_method     OUT colour mapping method
Pcolr_map_data     ** map_data      OUT colour mapping data

FORTRAN Syntax

SUBROUTINE pqpcmr ( WTYPE, CMRI, MLDR, ERRIND, MMETH, LDR, DATREC )

INTEGER             WTYPE                workstation type
INTEGER             CMRI                 predefined index
INTEGER             MLDR                 dimension of data record array
INTEGER             ERRIND               OUT error indicator
INTEGER             MMETH                OUT colour mapping method
INTEGER             LDR                  OUT number of array elements used
                                         in data record
CHARACTER* 80       DATREC(MLDR)         OUT data record

Required PHIGS Operating States

(PHOP, * ,* ,* )

DESCRIPTION

Purpose

INQUIRE PREDEFINED COLOUR MAPPING REPRESENTATION returns the values of a specified entry in the table of predefined colour mapping representations for the workstation type. Applications using the C binding must create a buffer for this function to use as a memory space for storing data associated with the device state. This buffer is passed as the store argument.

The store buffer is a data area that PHIGS manages. While the application is responsible for creating the initial buffer through a call to CREATE STORE, PHIGS manages this area so that there is sufficient memory for the specific inquiry. The data record in the store buffer is accessed by the pointer pointed to by map_data .

type

The type of workstation for which capabilities are inquired.

index

Entry in the workstation table of predefined colour mapping representations to be returned.

store

The memory buffer PHIGS is to use for storing the information returned. This buffer must exist prior to calling this function (see CREATE STORE (3P)).

C Output Parameters

error_ind

A pointer to the location in which to store the error number of any error that this function detects.

map_method

A pointer to a location in which to store the returned color mapping method.

map_data

A pointer to a pointer to a Pcolr_map_data structure, which contains information specific to the data mapping method. PHIGS allocates space for the structure in the Pstore object and returns the pointer to that allocated space in this parameter. Pcolr_map_data is defined in phigs.h as follows:

typedef union {

struct {

Pint

colr_model;

Pfloat_list

weights;

Pcolr_rep_list

colrs;

} method_r2

struct {

Pint

colr_model;

Pfloat_list_list

colr_lists;

} method_r3

} Pcolr_map_data;

Pfloat_list is defined in phigs.h as follows:

typedef struct {

Pint            num_floats;          /* number of Pfloats in list * /
Pfloat           * floats;            /* list of floats *

} Pfloat_list;

Pfloat_list_list is defined in phigs.h as follows:

typedef struct {

Pint            num_lists;          /* number of lists in list * /
Pfloat_list      * lists;            /* list of float lists * /

} Pfloat_list_list;

Pcolr_rep_list is defined in phigs.h as follows:

typedef struct {

Pint            num_colr_reps;      /* number of colours * /
Pcolr_rep       * colr_reps;        /* array of colours * /

} Pcolr_rep_list;

Pcolr_rep is defined in phigs.h as follows:

typedef union {

Prgb        rgb;        /* Red, Green, Blue colour specification * /
Pcieluv     cieluv;     /* CIE L* U* V* colour specification * /
Phls        hls;        /* Hue, Lightness, Saturation colour
                           specification * /
Phsv        hsv;        /* Hue, Saturation, Value colour
                           specification * /
Pdata       unsupp;     /* Colour in unsupported colour model * /

} Pcolr_rep;

Prgb is defined in phigs.h as follows:

typedef struct {

Pfloat           red;            /* red, hue, and so on * /
Pfloat           green;          /* green, saturation, lightness,
                                   and so on * /
Pfloat           blue;           /* blue, value, saturation,
                                   and so on * /

} Prgb;

Pcieluv is defined in phigs.h as follows:

typedef struct {

Pfloat           cieluv_x;       /* x coefficient * /
Pfloat           cieluv_y;       /* y coefficient * /
Pfloat           cieluv_y_lum; /* y luminance * /

} Pcieluv;

Phsv is defined in phigs.h as follows:

typedef struct {

Pfloat           hue;            /* hue * /
Pfloat           satur;          /* saturation * /
Pfloat           value;          /* value * /

} Phsv;

Phls is defined in phigs.h as follows:

typedef struct {

Pfloat           hue;            /* hue * /
Pfloat           lightness;      /* lightness * /
Pfloat           satur;          /* saturation * /

} Phls;

Pdata is defined in phigs.h as follows:

typedef struct {

size_t          size;           /* size of data * /
char            * data          /* pointerto data * /

} Pdata;

No data is associated with mapping method PCOLR_MAP_TRUE. The data for method PCOLR_MAP_PSEUDO is a list of weights and a list of direct colours. colr_model specifies the type of colours given in the list of colours, colrs . The colour models are defined in phigs.h as follows:

1

PMODEL_RGB

2

PMODEL_CIELUV

3

PMODEL_HSV

4

PMODEL_HLS

The data for mapping method PCOLR_MAP_PSEUDO_N is N lists of direct colours. These colours may be of the same types as for PCOLR_MAP_PSEUDO.

FORTRAN Input Parameters

Applications using the FORTRAN binding must supply a CHARACTER array to this function, into which the system will place the contents of the device's input data record. The contents of the data record are subsequently extracted by the application with the function UNPACK DATA RECORD (3P). The allocated dimension of the character array is passed in the MLDR argument. The dimension needed is returned in the LDR argument. The caller can determine the required dimension by calling this function with MLDR set to zero, in which case PHIGS returns the dimension needed in LDR.

Even if the dimension specified in MLDR is too small, including the case of its being zero, some values are returned. These are LDR, and the colour mapping method MMETH.

Error 2001 is returned when MLDR is too small; but not when it is zero.

WTYPE The type of workstation for which capabilities are inquired.

CMRI

Entry in the workstation table of predefined colour mapping representations to be returned.

MLDR

The dimension of the data record array, DATREC.

FORTRAN Output Parameters

ERRIND

The error number of any error detected by this function.

MMETH

The colour mapping method. This may be any of the following values defined in phigs77.h:

1

PCMAPTRUE

2

PCMAPPSEUDO

3

PCMAPPSEUDON

LDR

The required dimension of the data record array, DATREC.

DATREC

The data record array. This must subsequently be passed to UNPACK DATA RECORD (3P) to access its content. The content of the data record is determined by the colour mapping method; see SET COLOUR MAPPING REPRESENTATION (3P) for a content description.

Execution

If the inquired information is available, then the error indicator is returned as zero and values are returned in the output parameters.

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 this function detects an error.

ERRORS

002

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

051

Ignoring function, this information unavailable for this workstation type

052

Ignoring function, workstation type not recognized by the implementation

059

Ignoring function, the specified workstation does not have output capability (that is, the workstation category is not OUTPUT, OUTIN, or MO)

062

Ignoring function, this information is not available for this MO workstation type

102

Ignoring function, specified representation has not been predefined on this workstation

121

Ignoring function, the colour mapping index is less than 0 .

SEE ALSO

SET COLOUR MAPPING REPRESENTATION (3PP)

INQUIRE COLOUR MAPPING REPRESENTATION (3PP)

CREATE STORE (3P)

DELETE STORE (3P)

UNPACK DATA RECORD (3P)