15 CDBA Display Resource File Functions

This chapter describes the C functions that use the rules governing the display of design data.

A display resource file (usually named display.drf) contains display information which defines the colors, stipple patterns, line styles, and packets for display devices. A display device is anything that is drawn to or drawn on. It can be a computer monitor or a plotter. The default display device name is display, which is the computer monitor (be it color or black and white).

For more information on display resource files see the Virtuoso Technology Data User Guide.

For more information on display resource file functions in this chapter, see the following sections:

Moving the Display Resource Definition

You can move the display resource definition from your technology file to the display resources file so that the display resources can be shared by all layer-purpose pairs (via packet name references) in all the technology files. This serves the larger purpose of

Simplifying your technology file
Saving the X resources that specify color
Supporting a non-DFII application graphic
Sharing a display resource definition among libraries within a project

Using DRM Software

DRM (display resource management) software centralizes the management of display resources. When an application such as Layout Plus is initialized, the Display Resource Manager (DRM) loads the display.drf files.

Any time any of the defined resources are changed, by using the Display Resource Editor (DRE) or by calling a drSetPacket function, a trigger fires and informs internal applications of the change. For example, it might inform the Graphics Editor to redraw the screen.

With the new 5.00 technology file and DRM software, you can

Specify a packet’s display information
Map a layer-purpose pair to a packet that defines the fill color, outline color, stipple pattern, or line style.

Displays

The following functions create displays, delete displays, or give information about a display.

drCreateDisplay

drDisplayId

drCreateDisplay(
String         displayName,
unsigned int   maxNumberOfColors,
unsigned int   maxNumberOfStipples,
unsigned int   maxNumberOfLineStyles
);

Description

Creates a new display whose name is displayName and returns the identifier of the new display. The parameters maxNumberOfColors, maxNumberOfStipples, and maxNumberOfLineStyles declare the maximum number of colors, stipple patterns, and line styles for the display. It returns NULL if the display already exists or if not successful.

Arguments

`displayName`	The name of the new display.
`maxNumberOfColors`	The maximum number of colors specified.
`maxNumberOfStipples`	The maximum number of stipples specified.
`maxNumberOfLineStyles`
	The maximum number of line styles specified.

Return Value

drDisplayId

The identifier of the new display created.

drDeleteDisplay

Boolean

drDeleteDisplay(
drDisplayId  displayId
);

Description

Deletes the display identified by displayId.

Arguments

displayId

The identifier of the display.

Return Value

Boolean

The function returns TRUE if the display is deleted successfully; otherwise, it returns FALSE.

drGetDisplayId

drDisplayId

drGetDisplayId(
displayName
);

String  displayName;

Description

Returns the display identifier of the display whose name is displayName.

Arguments

displayId

The identifier of the display.

Return Value

drDisplayId

The function returns NULL if the display does not exist or if is not successful.

drIsDisplayId

Boolean

drIsDisplayId(
displayId
);

drDisplayId  displayId

Description

Checks whether the identifier of a display is valid.

Arguments

displayId

The identifier of the display.

Return Value

Boolean

Returns TRUE if displayId is a valid display identifier; otherwise, it returns FALSE.

drGetDisplayName

String

drGetDisplayName(
displayId
);

drDisplayId  displayId;

Description

Returns the name of the display specified by displayId.

Arguments

displayId

The identifier of the display.

Return Value

String

The name of the display. The function returns NULL if the identifier is not a valid display identifier.

drGetDisplayMaxColors

unsigned int

drGetDisplayMaxColors(
drDisplayId    displayId
);

Description

Returns the maximum number of colors allowed in the display specified by displayId.

Arguments

displayId

The identifier of the display.

Return Value

unsigned int

The maximum number of colors allowed in the display. The function returns 0 if the identifier is not a valid display identifier.

drGetDisplayMaxStipples

unsigned int

drGetDisplayMaxStipples(
displayId
);

drDisplayId  displayId;

Description

Returns the maximum number of stipple patterns allowed in the display specified by displayId.

Arguments

displayId

The identifier of the display.

Return Value

unsigned int

The maximum number of stipple patterns allowed in the display. The function returns 0 if the identifier is not a valid display identifier.

drGetDisplayMaxLineStyles

unsigned int

drGetDisplayMaxLineStyles(
drDisplayId    displayId
);

Description

Returns the maximum number of line styles allowed in the display specified by displayId.

Arguments

displayId

The identifier of the display.

Return Value

unsigned int

The maximum number of line styles allowed in the display. The function returns 0 if the identifier is not a valid display identifier.

drStartGenDisplay

drGenStateId

drStartGenDisplay(
);

Description

Starts the generator for all displays.

Arguments

None.

Return Value

drGenStateId

The generator state identifier to be used with the drGenDisplay function.

drGenDisplay

Boolean

drGenDisplay(
drGenStateId   state,
drDisplayId    *pDisplayId
);

Description

This generator function generates display identifiers for all the displays.

Arguments

`state`	The generator state identifier returned by the `drStartGenDisplay` function.
`*pDisplayId`	The pointer to the display identifier variable.

Return Value

Boolean

If the function returns TRUE, *pDisplayId has been assigned the next valid display identifier generated.

The function returns FALSE if the generator state identifier is invalid, if the display identifiers are invalid, or if the generator is finished.

Display-Dependent Attributes

Display-dependent attributes are those that refer to entries in the display’s tables. When setting or retrieving these attributes, you must specify the display identifier, because it is possible that a packet may refer to two different display devices for the same attribute.

The following are functions for display-dependent attributes.

drGetPacketFillColor

Boolean

drGetPacketFillColor(
drDisplayId     displayId,
String          packetName,
drColor         **ppColor
);

Description

Returns the packet fill color used in a display.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.
`**ppColor`	The packet fill color.

Return Value

Boolean

The function returns TRUE and the packet fill color argument updated for the specified display identifier and packet name. It returns FALSE if it is not successful.

drGetPacketFillColorIndex

int

drGetPacketFillColorIndex(
drDisplayId     displayId,
String          packetName
);

Description

Returns the packet fill color specified by displayId and packetName. The color is returned as an index into the display’s color table. The drGetColor function retrieves the RGB values given in the color index.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.

Return Value

int

The packet fill color index specified by displayId and packetName. The function returns -1 if the packet’s fill color is not defined or successful.

drGetPacketFillColorName

String

drGetPacketFillColorName(
drDisplayId     displayId,
String          packetName
);

Description

Returns the packet’s fill color name specified by displayId and packetName.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.

Return Value

String

The packet’s fill color name specified by displayId and packetName. The function returns NULL if the packet’s fill color is not defined or if not successful.

drSetPacketFillColor

Boolean

drSetPacketFillColor(
drDisplayId     displayId,
String          packetName,
unsigned int    colorIndex
);

Description

Sets the fill color of the packet specified by displayId and packetName to the one specified by colorIndex. The colorIndex must not exceed the maximum number of entries allocated for the color table in the drCreateDisplay call.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.
`colorIndex`	The color index.

Return Value

Boolean

The function returns TRUE if modification is successful; otherwise, it returns FALSE.

drGetPacketOutlineColor

Boolean

drGetPacketOutlineColor(
drDisplayId     displayId,
String          packetName,
drColor         **ppColor
);

Description

Returns the packet outline color specified by displayId and packetName.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.
`**ppColor`	The packet outline color.

Return Value

Boolean

The function returns TRUE and the packet outline color specified by displayId and packetName. It returns FALSE if not successful.

drGetPacketOutlineColorIndex

int

drGetPacketOutlineColorIndex(
drDisplayId     displayId,
String          packetName
);

Description

Returns the packet outline color index specified by displayId and packetName. The color is returned as an index into the display’s color table. The drGetColor function retrieves the RGB values given in the color index.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.

Return Value

int

The packet outline color specified by displayId and packetName. The function returns -1 if the packet’s outline color is not defined or if not successful.

drGetPacketOutlineColorName

String

drGetPacketOutlineColorName(
drDisplayId     displayId,
String          packetName
);

Description

Returns the packet’s outline color name specified by displayId and packetName.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.

Return Value

String

The packet’s outline color name specified by displayId and packetName.The function returns NULL if the packet’s outline color is not defined or if not successful.

drSetPacketOutlineColor

Boolean

drSetPacketOutlineColor(
drDisplayId     displayId,
String          packetName,
unsigned int    colorIndex
);

Description

Sets the outline color of the packet specified by displayId and packetName to the one specified by colorIndex. The colorIndex must not exceed the maximum number of entries allocated for the color table in the drCreateDisplay call.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.
`colorIndex`	The color index specifying the outline color.

Return Value

Boolean

The function returns TRUE if modification is successful; otherwise, it returns FALSE.

drGetPacketStipple

Boolean

drGetPacketStipple(
drDisplayId     displayId,
String          packetName,
drStipple       **ppStipple
);

Description

The function returns TRUE with a NULL stipple pointer if the stipple of the specified packet is _NA_.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.
`**ppStipple`	The packet stipple.

Return Value

Boolean

The function returns FALSE if it is not successful. The function returns TRUE and the packet stipple specified by displayId, and the packet name if the stipple of the specified packet is defined.

drGetPacketStippleIndex

int

drGetPacketStippleIndex(
drDisplayId     displayId,
String          packetName
);

Description

Returns the packet stipple pattern index specified by displayId and packetName. The stipple pattern is returned as an index into the display’s stipple table. The drGetStipple function retrieves the stipple pattern given in the stipple index.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.

Return Value

int

The packet stipple pattern specified by displayId and packetName. The function returns -1 if the packet’s stipple pattern is not defined or if not successful.

drGetPacketStippleName

String

drGetPacketStippleName(
drDisplayId     displayId,
String          packetName
);

Description

Returns the packet’s stipple name specified by displayId and packetName.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.

Return Value

String

The function returns NULL if the packet’s stipple pattern is not defined or if not successful.

drGetPacketFillStyle

Boolean

drGetPacketFillStyle(
drDisplayId     displayId,
String          packetName
);

Description

Returns the packet’s fill style in a display.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.

Return Value

Boolean

The function returns NULL if the packet’s fill style is not defined or if the function is not successful.

drSetPacketFillStyle

Boolean

drSetPacketFillStyle(
drDisplayId        displayId,
String             packetName,
drPacketFillStyle  fillStyle
);

Description

Returns the packet’s fill style in a display.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.
`fillStyle`	The packet’s fill style.

Return Value

Boolean

The function returns NULL if the packet’s fill style is not defined or if the function is not successful.

drSetPacketStipple

Boolean

drSetPacketStipple(
drDisplayId     displayId,
String          packetName,
unsigned int    stippleIndex
);

Description

Sets the stipple pattern of the packet specified by displayId and packetName to the one specified by stippleIndex. The stippleIndex must not exceed the maximum number of entries allocated for the stipple table in the drCreateDisplay call.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.
`stippleIndex`	The stipple index.

Return Value

Boolean

The function returns TRUE if modification is successful; otherwise, it returns FALSE.

drGetPacketLineStyle

Boolean

drGetPacketLineStyle(
drDisplayId     displayId,
String          packetName,
drLineStyle     **ppLineStyle
);

Description

Returns the packet line style specified by displayId and packetName. The drGetLineStyle function retrieves the line style pattern when given the line style index.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.
`**ppLineStyle`	The packet’s line style.

Return Value

Boolean

The function returns TRUE and the packet line style specified by displayId and packetName. The function returns FALSE if the packet’s line style is not defined or if not successful.

drGetPacketLineStyleIndex

int

drGetPacketLineStyleIndex(
drDisplayId     displayId,
String          packetName
);

Description

Returns the packet line style index specified by displayId and packet name.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.

Return Value

int

Returns the index of the line style. The function returns -1 if the packet line style index is not found or if the function is not successful.

drGetPacketLineStyleName

String

drGetPacketLineStyleName(
drDisplayId     displayId,
String          packetName
);

Description

Returns the packet’s line style name specified by displayId and packetName.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.

Return Value

String

The function returns NULL if the packet’s line style is not defined or if the function is not successful.

drSetPacketLineStyle

Boolean

drSetPacketLineStyle(
drDisplayId     displayId,
String          packetName,
unsigned int    lineStyleIndex
);

Description

Sets the line style of the packet specified by displayId and packetName to the one specified by lineStyleIndex. The lineStyleIndex must not exceed the maximum number of entries allocated for the line style table in the drCreateDisplay call.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.
`lineStyleIndex`	The index of the line style.

Return Value

Boolean

The function returns TRUE if modification is successful; otherwise, it returns FALSE.

drSetStipple

Boolean

drSetStipple(
drDisplayId     displayId,
String          stippleName,
unsigned int    width,
unsigned int    height,
unsigned char   *pattern
);

Description

Stores stipple information in the stipple table of the display resource manager and calls the application stipple modification trigger to update the stipple’s pixel map in the graphics library.

Arguments

`displayId`	The identifier of the display.
`stippleName`	The stipple name.
`width`	The width of the stipple.
`height`	The height of the stipple.
`*pattern`	The stipple pattern.

Return Value

Boolean

The function returns TRUE if the stipple’s pixel map in the graphics library is successfully updated. Otherwise, it returns FALSE.

drFreeStipple

Boolean

drFreeStipple(
unsigned int   drDisplayId  displayId,
String         stippleName
);

Description

Deletes the specified stipple from the DRM.

Arguments

`displayId`	The identifier of the display.
`stippleName`	The stipple name.

Return Value

Boolean

Returns TRUE if the deletion is successfully performed; otherwise, the function returns FALSE.

drSetLineStyle

Boolean

drSetLineStyle(
drDisplayId     displayId,
String          lineStyleName,
unsigned int    width,
unsigned int    length,
unsigned char   *pattern
);

Description

Stores line style information in the line style table of the DRM and calls the application’s line style modification trigger to update the line style’s dash list in the graphics library.

Arguments

`displayId`	The identifier of the display.
`lineStyleName`	The name of the line style.
`width`	The width of the line.
`length`	The length of the line.
`*pattern`	The address of the line style table, returned by indirection.

Return Value

Boolean

Returns TRUE if the information is successfully stored; otherwise, the function returns FALSE.

drFreeLineStyle

Boolean

drFreeLineStyle(
drDisplayId    displayId,
String         lineStyleName
);

Description

Deletes the specified line style from the DRM.

Arguments

`displayId`	The identifier of the display.
`lineStyleName`	The name of the line style.

Return Value

Boolean

Returns TRUE if the line style is successfully deleted. Otherwise, the function returns FALSE.

drSetPacket

extern Boolean

drSetPacket(
drDisplayId          displayId,
String               packetName,
String               stippleName,
String               lineStyleName,
String               fillColorName,
String               outlineColorName
drPacketFillStyle    fillStyle
);

enum drPacketFillStyle {
    drcPacketUnknownFill         = 0, /* alias layerFillUnknown */
    drcPacketOutlineFill         = 1, /* alias layerOutlineNoFill */
    drcPacketSolidFill           = 2, /* alias layerSolidFill */
    drcPacketXFill               = 3, /* alias xFill */
    drcPacketStippleFill         = 4, /* alias layerStippleFill */
    drcPacketOutlineStippleFill  = 5, /* alias layerOutlineStippleFill */
    drcPacketFillStyleNotDecided = 6  /* Not decided yet. */
};

Description

Selectively changes items in a packet. Fill colors, outline colors, stipples, line styles, or fill styles may be changed. Items passed as NULL will not be changed. This routine does not only change these values in the DRM (design rule manager) database, but also triggers the applications to update their pen in the graphics library database.If an attribute is not NULL then that attribute updated, for example, if stippleName == "dots", then the packet now uses "dots" as its stipple. The last is a drPacketFillType enum. If its value is set to drPacketUnknownFill, then no change is made, else it should be set.

Arguments

`displayId`	The identifier of the display.
`packetName`	The name of the packet.
`stippleName`	The stipple name.
`lineStyleName`	The name of the line style.
`fillColorName`	The name of the fill color.
`outlineColorName`	The name of the outline color.
`fillStyle`	The name of the fill style.

Return Value

Boolean

The function returns TRUE if the selected items are successfully changed. Otherwise, the function returns FALSE.

drmInit

String

drmInit(
int       *pArgc,
char      **pArgv
);

Description

Initializes the display resource manager program.

Arguments

The argument count and argument vector, as passed to your program’s main function.

Return Value

String

The current version of the display resource manager software (such as 4.4.3 or 5.0.0).

drOpenDrf

Boolean

drOpenDrf( 
String      drfPath,
Boolean     askToSave
);

Description

Opens a display resource file and gives you the option of not seeing the prompt to save upon exit. (Many users merge in or load in display resource files while editing but have no intention of saving them.)

Arguments

`drfPath`	The path to the display resource file.
`askToSave`	The option to be queried to save the changes to the display resource file.

Return Value

Boolean

The function returns TRUE if it successfully locates the path to the display resource file and loads the file. If TRUE, if you have modified but not saved any display resource file changes on exit, you are queried to save the changes. Examples of changes are using the DRE (display resource environment) or merging or loading your file into another display resource file.

If the function returns FALSE, either the path to the display was not successfully located, or if it does open the display resource file, you are not prompted to save the file upon exit even if you have modified but not saved internal display resource file information.

drSave

extern Boolean

drSave(
String      filename
Boolean     incSave
);

Description

Writes (saves) the updated virtual memory version of the information you have changed to a disk display resource (display.drf) file.

Arguments

`filename`	The name of the display resource file to save.
`incSave`	If the value of the 2nd parameter, `incSave`, is TRUE, drm saves all changed display information only. If the value of the 2nd parameter, `incSave`, is FALSE, drm saves all current display information into the specified `display.drf` file.

Return Value

Boolean

The function returns TRUE if the file is successfully saved; otherwise, it returns FALSE.

Colors

A packet may have three colors defined for drawing objects:

Fill color
Outline color
Bright color

Unselected objects on the packet are filled with the fill color and their outline is drawn with the outline color. In most cases the fill color and the outline color will be the same.

Selected objects on the packet are drawn with bright color.

Colors are stored in a display’s color table and are addressed either by the color table index or the color name. The color table index is guaranteed to be unique and to remain the same during the lifetime of the color table.

General Data Structures to Generate Colors

The following data structures are used to set up colors for objects in a packet.

drColorStructure

The color parameters are specified in the structure of type drColor.

typedef struct drColor drColor;

struct drColor {
String name; unsigned long index; unsigned short red, green, blue;
};

Description

Creates an array of color parameters.

Argument

`name`	The field `name` specifies the color name.
`index`	The field `index` specifies the color index in the color table.
`red`, `green`, `blue`	The fields `red`, `green`, and `blue` specify the red, green, and blue components of the color. When making a color, all the fields must be initialized.

drMakeColor

Boolean

drMakeColor(
drDisplayId displayId,
drColor *pColor
);

Description

Makes a color in the display’s color table. If the color does not exist, it is created. If the color exists, its parameters are updated. The color index uniquely identifies the color.

Arguments

`displayId`	The identifier of the display.
`*pColor`	The pointer to a `drColor` data structure.

Return Value

Boolean

The function returns TRUE if the creation or modification is successful; otherwise, it returns FALSE.

drGetNumberOfColors

int

drGetNumberOfColors(
     drDisplayId displayId
);

Description

Returns the number of colors in a display specified by displayId.

Arguments

displayId

The identifier of the display.

Return Value

int

The number of colors in the specified display.

drSetColorBlink

Boolean

drSetColorBlink(
drDisplayId   displayId,
unsigned int  colorIndex,
Boolean       *pBlink
);

Description

Sets the specified color to blink.

Arguments

`displayId`	The identifier of the display.
`colorIndex`	The color index which uniquely identifies the color.
`*pBlink`	The state indicating whether the color is set to blink or not.

Return Value

Boolean

Returns TRUE if the color is set to blink. Returns FALSE if the function did not successfully set the color to blink, such as if no color is identified.

drGetColorBlink

Boolean

drGetColorBlink(
drDisplayId   displayId,
unsigned int  colorIndex,
Boolean       *pBlink
);

Description

Returns the information on whether a specified color is set to blink.

Arguments

`displayId`	The identifier of the display.
`colorIndex`	The color index which uniquely identifies the color.
`*pBlink`	The state indicating whether the color is set to blink or not.

Return Value

Boolean

Returns TRUE if the display and color index are legal. If the function returns TRUE, the value of the argument pointer *pBlink has been updated. If its value is TRUE, the color is blinking.

Returns FALSE if the display or color index are invalid. If the value of the argument pointer is FALSE, the color does not blink. In this case, the value of *pBlink is undefined and should not be used.

drGetColor

drColor *

drGetColor(
drDisplayId   displayId,
unsigned int  colorIndex
);

Description

The structure contents specified by the pointer returned is valid only until the next call to drGetColor or drGetColorByName.

Arguments

`displayId`	The identifier of the display.
`colorIndex`	The index uniquely identifying the color.

Return Value

drColor *

Returns the color from the color table index. The function returns NULL if the color index or display identifier are invalid or if the function is not successful.

drGetColorByName

drColor *

drGetColorByName(
drDisplayId  displayId,
String       colorName
);

Description

Returns the first color the color name refers to. The structure contents specified by the pointer returned is valid only until the next call to drGetColor or drGetColorByName.

Arguments

`displayId`	The identifier of the display.
`colorName`	The name of the color.

Return Value

drColor *

It returns NULL if the color display identifier is not defined or if not successful.

drGetColorIndexByName

int

drGetColorIndexByName(
drDisplayId   displayId,
String        colorName
);

Description

Returns the color index from the color name. Use this routine when you want to verify if a named color has been defined, without being interested in the color structure.

Arguments

`displayId`	The identifier of the display.
`colorName`	The name of the color.

Return Value

int

The function returns the color index if successful. Otherwise, it returns -1 if the color is not defined or if not successful.

drStartGenColor

drGenStateId

drStartGenColor(
drDisplayId displayId
);

Description

Starts the generator function for colors of a display.

Arguments

displayId

The identifier of the display.

Return Value

drGenStateId

Returns a valid drGenStateId if the function is successfully completed. Returns NULL if not, or if the display is not successfully identified.

drGenColor

Boolean

drGenColor(
state, **packetPP
);

drGenStateId state;
drColor **color;

Description

Generates the next color of a display.

Arguments

`state`	The generator state identifier returned by the `drStartGenColor` function.
`**color`	The next color for a display which is generated, returned by indirection.

Return Value

Boolean

The function returns FALSE if the generator state identifier is invalid, or if the generator is finished.

Functions to Generate DRM Colors

These generator functions generate all DRM (Display Resource Manager) colors associated with the specified display device.

drGenStateId pState;
drDisplayId displayId;
drColor *colorP;

...
pState = drStartGenColor(displayId);
if ( !pState ) {
     fprintf("DRM: Failed to generate colors.\n");
     return FALSE;
}
while (drGenColor(pState, &colorP)) {
     printf("Color Name %s\n", colorP->name);
}

drStopGen(pState);

When you call a display resources generator to generate a display, color, stipple, linestyle, or packet, remember to call drStopGen() when finished, to properly terminate the generator.

Stipple Patterns

A stipple pattern fills shapes on a packet if the packet’s fill style specifies to use a fill pattern. Stipple patterns are stored in the display’s stipple table and they are addressed either by the stipple table index or the stipple name. The stipple table index is guaranteed to be unique and to remain the same during the life time of the stipple table. The stipple pattern parameters are specified in a structure of type drStipple. This section gives a structure and functions for stipple patterns.

drStipple

typedef struct drStipple drStipple;
struct          drStipple {
String          name;
unsigned int    index;
unsigned int    width;
unsigned int    height;
unsigned char   *pattern;
};

Description

Creates a stipple pattern. Each element may have either the value 0 or the value 1. Given the index of a bit in the pattern, its row and column are calculated as:

row = index / width

column = index % width

When making a stipple pattern, initialize all fields.

Arguments

`drStipple`	The name of the structure.
`name`	The field `name` specifies the stipple name.
`index`	The field `index` specifies the index of the stipple pattern in the stipple table.
`width`	The field `width` specifies the width of the stipple pattern in pixels.
`height`	The field `height` specifies the height of the stipple pattern in pixels.
`pattern`	The field `pattern` is a pointer to a linear representation of the two dimensional stipple pattern, where each one byte element represents a bit in the stipple pattern.

drMakeStipple

Boolean

drMakeStipple(
drDisplayId  displayId,
drStipple    *pStipple
);

Description

Makes a stipple pattern in the display’s stipple table. If the stipple pattern does not exist, it is created. If the stipple pattern exists, its parameters are updated. The stipple index uniquely identifies the stipple pattern.

Arguments

`displayId`	The identifier of the display.
`*pStipple`	The pointer to the `drStipple` initialized data structure. it describes the stipple to create or update.

Return Value

Boolean

The function returns TRUE if the modification or creation is successful; otherwise, it returns FALSE.

drGetStipple

drStipple *

drGetStipple(
drDisplayId   displayId,
unsigned int  stippleIndex
);

Description

Returns the stipple pattern specified by the stipple index. The structure contents specified by the pointer returned are valid only until the next call to drGetStipple or drGetStippleByName.

Arguments

`displayId`	The identifier of the display.
`stippleIndex`	The stipple index.

Return Value

drStipple *

The function returns NULL if the stipple pattern is not defined, if the display identifier is not valid, or if the function is not successful.

drGetStippleByName

drStipple *

drGetStippleByName(
drDisplayId   displayId,
String        stippleName
);

Description

Returns the stipple pattern specified by the stipple name. The structure contents specified by the pointer returned are valid only until the next call to drGetStipple or drGetStippleByName.

Arguments

`displayId`	The identifier of the display.
`stippleName`	The stipple name.

Return Value

drStipple *

The function returns NULL if the stipple pattern is not defined, if the display identifier is invalid, or if the function is not successful.

drDeleteStippleByName

Boolean

drDeleteStippleByName(
drDisplayId   displayId,
String        stippleName
);

Description

Deletes the stipple pattern specified by the stipple name.

Arguments

`displayId`	The identifier of the display.
`stippleName`	The stipple name.

Return Value

Boolean

The function returns TRUE is the stipple was deleted. The function returns FALSE if the display identifier or the stipple name is invalid, or if the stipple was not deleted.

drGetStippleIndexByName

int

drGetStippleIndexByName(
drDisplayId  displayId,
String       stippleName
);

Description

Returns the index of the stipple pattern specified by the stipple name. This routine is used when you want to verify if a named stipple pattern has been defined, without being interested in the pattern.

Arguments

`displayId`	The identifier of the display.
`stippleName`	The stipple name.

Return Value

int

The index of the stipple pattern specified by the stipple name. The function returns -1 if the stipple pattern is not defined or if not successful.

drStartGenStipple

drGenStateId

drStartGenStipple(
drDisplayId displayId
);

Description

Prepares to generate all DRM stipples associated with the specified display device.

Arguments

displayId

The identifier of the display.

Return Value

drGenStateId

The generator state identifier to be used in the drGenStipple function.

drGetNumberOfStipple

int

drGetNumberOfStipple(
displayId
);

Description

Retrieves the number of DRM (Display Resource Manager) stipples associated with the specified display device.

Arguments

displayId

The identifier of the display.

Return Value

int

The number of DRM stipples returned.

drGenStipple

Boolean

drGenStipple(
drGenStateId  state,
drStipple     **stipple
);

Description

Generates all DRM stipples associated with the specified display device.

Arguments

`state`	The generator state identifier returned by the `drStartGenStipple` function.
`**stipple`	The next stipple generated.

Return Value

Boolean

The function returns FALSE if the generator state identifier is invalid, if the stipples do not exist, or if the generator is finished. If the function returns TRUE, the stipple updated points to the drStipple data structure.

Line Styles

Line styles are stored in the display’s line style table. They are addressed by either the line style table index or the line style name. The line style table index is guaranteed to be unique and to remain the same during the lifetime of the line style table. The line style parameters are specified in a structure of type drLineStyle.

This section gives a structure and functions for line styles.

drLineStyle

typedef struct drLineStyle drLineStyle;
struct drLineStyle {
String         name;
unsigned int   index;
unsigned int   length;
unsigned int   width;
unsigned char  *pattern;
};

Description

The line style data structure.

Arguments

`name`	The field `name` specifies the line style name.
`index`	The field `index` specifies the index of the line style in the line style table.
`length`	The field `length` specifies the length of the line style pattern in pixels.
`width`	The field `width` specifies the width of the line in pixels.
`*pattern`	The field *`pattern` is a pointer to an array of bytes where each one byte element represents a bit in the line style pattern.

drMakeLineStyle

Boolean

drMakeLineStyle(
drDisplayId   displayId,
drLineStyle   *pLineStyle
);

Description

Makes a line style in the display’s line style table. If the line style does not exist, it is created. If the line style exists, its parameters are updated. The line style index uniquely identifies the line style.

Arguments

`displayId`	The identifier of the display.
`*pLineStyle`	The pointer to the line style.

Return Value

Boolean

The function returns TRUE if the creation or modification is successful; otherwise, it returns FALSE.

drGetLineStyle

drLineStyle *

drGetLineStyle(
drDisplayId    displayId,
unsigned int   lineStyleIndex
);

Description

Returns the line style specified by the line style index. The structure contents specified by the pointer returned is valid only until the next call to drGetLineStyle or drGetLineStyleByName.

Arguments

`displayId`	The identifier of the display.
`lineStyleIndex`	The line style index.

Return Value

drLineStyle *

The line style specified by the line style index. The function returns NULL if the line style is not defined or if not successful.

drGetLineStyleByName

drLineStyle *

drGetLineStyleByName(
drDisplayId   displayId,
String        lineStyleName
);

Description

Returns the first line style specified by the line style name. The structure contents specified by the pointer returned is valid only until the next call to drGetLineStyle or drGetLineStyleByName.

Arguments

`displayId`	The identifier of the display.
`lineStyleName`	The line style name.

Return Value

drLineStyle *

The first line style specified by the line style name. The function returns NULL if the line style is not defined or if not successful.

drGetLineStyleIndexByName

int

drGetLineStyleIndexByName(
drDisplayId   displayId,
String        lineStyleName
);

Description

Returns the index of the line style specified by the line style name. This routine is used when you want to verify if a named line style has been defined, without being interested in the line style.

Arguments

`displayId`	The identifier of the display.
`lineStyleName`	The line style name.

Return Value

int

The index of the line style specified by the line style name. The function returns -1 if the line style is not defined or if not successful.

drStartGenLineStyle

drGenStateId

drStartGenLineStyle(
drDisplayId displayId
);

Description

Starts the generator to generate the line styles in a display.

Arguments

displayId

The identifier of the display.

Return Value

drGenStateId

The generator state identifier to be used in the drGenLineStyle function.

drGenLineStyle

Boolean

drGenLineStyle(
drGenStateId   pState,
drLineStyle**  lineStyle
);

Description

Generates the line styles in a display.

Arguments

`pState`	The generator state identifier returned by the `drStartGenLineStyle` function.
`lineStyle **`	The next line style generated.

Return Value

Boolean

If the function returns TRUE, the function is successful and the line style argument is assigned and valid. If the generator state identifier or the line style is invalid, or if the generator is finished, this function returns FALSE.

Packets

Packet are stored in the display’s packet hash table. They are addressed by the packet name. This section gives a structure and functions for packets.

The packet parameters are specified in a structure of type drPacket.

drPacket
typedef struct drPacket drPacket;
struct drPacket {
String name;
unsigned int stipIdx;
unsigned int lineStyleIdx;
unsigned int fillIdx;
unsigned int outlineIdx;
};

Description

The value of stipIdx of a packet is USHRT_MAX(65535) if the user specifies _NA_ or _na_stipple for a packet. The value of lineStyleIdx of a packet is USHRT_MAX(65535) if the user specifies _NA_ or _na_ for a packet. The value of outlineIdx is same as the value of fillIdx if the user specifies _DEF_ or _def_ for a packet.

Arguments

`name`	The field `name` specifies the packet name.
`stipIdx`	The field `stipIdx` specifies the index of the stipple in the stipple table.
`lineStyleIdx`	The field `lineStyleIdx` specifies the index of the line style in the line style table.
`fillIdx`	The field `fillIdx` specifies the index of the fill color in the color table.
`outlindIdx`	The field `outlineIdx` specifies the index of the outline color in the color table.

drMakePacket

Boolean

drMakePacket(
drDisplayId  displayId
drPacket     *pPacket
);

Description

Makes a packet in the display’s packet hash table. If the packet does not exist, it is created. If the packet exists, its parameters are updated. The packet name uniquely identifies the packet.

Arguments

`displayId`	The identifier of the display.
`*pPacket`	The address of the packet.

Return Value

Boolean

The function returns TRUE if the modification is successful; otherwise, it returns FALSE.

drGetPacket

drPacket *

drGetPacket(
drDisplayId   displayId,
String        PacketName
);

Description

Returns the packet specified by the packet name.

Arguments

`displayId`	The identifier of the display.
`PacketName`	The specified packet name.

Return Value

drPacket *

The packet. The function returns NULL if the packet is not defined or if not successful.

drDeletePacket

void

drDeletePacket(
drDisplayId   displayId,
String        PacketName
);

Description

Deletes a packet in a display.

Arguments

`displayId`	The identifier of the display.
`PacketName`	The packet name.

Return Value

None.

drMakePacketAlias

Boolean

drMakePacketAlias(
drDisplayId   displayId,
String        aliasPacketName,
String        srcPacketName
);

Description

Creates an alias for a packet name.

Arguments

`displayId`	The identifier of the display.
`aliasPacketName`	The alias for the packet name.
`srcPacketName`	The original packet name.

Return Value

Boolean

Returns TRUE if the alias is successfully created. Returns FALSE if the display or packet name is not successfully identified.

drGetNumberOfPackets

int

drGetNumberOfPackets(
displayId
);

drDisplayId  displayId;

Description

Returns the number of packets in a display.

Arguments

displayId

The identifier of the display.

Return Value

int

The number of packets in a display.

drGetPacketIndex

drPacketId

drGetPacketIndex(
drDisplayId   displayId,
String        PacketName
);

Description

Returns the identifier of a packet in a display.

Arguments

`displayId`	The identifier of the display.
`PacketName`	The packet name.

Return Value

drPacketId

The identifier of the packet.

drFindPacket

drPacket *

drFindPacket(
drDisplayId   displayId,
String        PacketName
);

Description

Locates a packet in a display.

Arguments

`displayId`	The identifier of the display.
`PacketName`	The packet name.

Return Value

drPacket *

The packet.

drMakeDefaultPacket

drPacket *

drMakeDefaultPacket(
drDisplayId   displayId,
String        func
);

Description

Creates a default packet in a display.

Arguments

`displayId`	The identifier of the display.
`func`	The name of the calling function.

Return Value

drPacket *

The default packet created.

drStartGenPacketIndex

drGenStateId

drStartGenPacket(
drDisplayId displayId
);

Description

Starts the generator to generate a packet index for a display.

Arguments

displayId

The identifier of the display.

Return Value

drGenStateId

The generator state identifier to be used in the drGenPacket function.

drGenPacket

Boolean

drGenPacket(
state, **packetPP
);

drGenStateId  state;
drPacket  **packetPP;

Description

Generates all DRM (display resource management) packets associated with the specified display device.

Arguments

`state`	The generator state identifier returned by the `drStartGenPacket` function.
`**packetPP`	The display resource management packets to be generated.

Return Value

Boolean

If the DRM packets do not exist, the generator state identifier is invalid, or the generator is finished, this function returns FALSE.

Return to top

Cadence Integrators Toolkit Database ReferenceProduct Version IC23.1, June 2023

15

CDBA Display Resource File Functions

Moving the Display Resource Definition

Using DRM Software

Displays

drCreateDisplay

Description

Arguments

Return Value

drDeleteDisplay

Description

Arguments

Return Value

drGetDisplayId

Description

Arguments

Return Value

drIsDisplayId

Description

Arguments

Return Value

drGetDisplayName

Description

Arguments

Return Value

drGetDisplayMaxColors

Description

Arguments

Return Value

drGetDisplayMaxStipples

Description

Arguments

Return Value

drGetDisplayMaxLineStyles

Description

Arguments

Return Value

drStartGenDisplay

Description

Arguments

Return Value

drGenDisplay

Description

Arguments

Return Value

Display-Dependent Attributes

drGetPacketFillColor

Description

Arguments

Return Value

drGetPacketFillColorIndex

Description

Arguments

Return Value

drGetPacketFillColorName

Description

Arguments

Return Value

drSetPacketFillColor

Description

Arguments

Return Value

drGetPacketOutlineColor

Description

Arguments

Return Value

drGetPacketOutlineColorIndex

Description

Arguments

Return Value

drGetPacketOutlineColorName

Description

Arguments

Return Value

drSetPacketOutlineColor

Description

Arguments

Return Value

drGetPacketStipple

Cadence Integrators Toolkit Database Reference
Product Version IC23.1, June 2023