CGINEWS(3X) — UNIX Programmer’s Manual

NAME

cginews − NEWS CGI library

SYNOPSIS

#include <cgi.h> ccfile.c ... −lcginews −lm
lintfile.c ... −lcginews −lm

DESCRIPTION

CGI (Computer Graphics Interface) is a graphics device interface being standardized by ISO (International Organization for Standards). In the context of ISO graphics standards, GKS (Graphical Kernel System), GKS-3D, and PHIGS (Programmer’s Hierarchical Interactive Graphics System) specify the API (Application Program Interface), which is the interface between application programs and graphics systems, while CGI specifies the VDI (Virtual Device Interface), which is the interface between graphics systems and graphics devices.

CGI specifies abstract functions which any graphics devices or graphics device drivers should provide to obtain device independence. CGI specifies more than 200 functions, which are classified as follows.

(1) control and negotiation functions
(a) virtual device management, which allows the application and the device initiate and terminate sessions of dialogue and to manage the graphics image on the virtual device, (b) negotiation, which allows the graphics application system to interrogate the device in order to learn its capabilities and to select an appropriate mode of operation, (c) coordinate space control for the establishment of protocols for the transmission of coordinate information, placement of the picture on the view surface, and for the management of clipping, (d) error management, which involves the detection of errors both at and below the level of the parameters transmitted through CGI protocol, and (e) miscellaneous control elements, which include the external elements and protocols.

(2) output and attribute functions
(a) graphical primitives, which describe the visual components of a picture, (b) attribute functions, which describe the appearance of graphical primitives, (c) control elements, which specify the modes of operation of certain other functions and control some aspects of the device’s operation, (d) interrogation functions (for output and attribute capabilities), which allow the CGI user to determine what the device can do, (e) inquiry functions (for output and attribute capabilities), which allow the CGI user to obtain information about the current values in the CGI state list.

(3) input functions
There are six input classes: CHOICE, LOCATOR, STROKE, STRING, VALUATOR, and PICK, and there are four modes of operation: REQUEST, SAMPLE, EVENT, and ECHO REQUEST.

(4) segmentation functions
Functions for creating, modifying and manipulating segments are specified.

(5) raster operation functions
Functions for raster operations are specified. The CGI user can select drawing bitmap and display bitmaps, can create and delete bitmaps, and can change the contents of bitmap by BITBLT operations.

CGI’s partioning concept divides these functions into minimum required function sets called CGIMIN and INPUT CGIMIN, and the following Option Sets:

Output
Settable Bundles Option Set
Closed Figure Option Set

Segmentation
Segmentation Option Set

Input
Sample Option Set
Event Option Set
Remote Echo Option Set
Echo Option Set
Echo Output Option Set

Raster
Raster Option Set

This implementation supports all of the above Option Sets except the Closed Figure , Segmentation, and Event Option Sets,
but not completely.

FUNCTIONS

CGI CONTROL virtual device managemant functions
CGI_Initialise()initialise CGI
CGI_Reset_To_Defaults()reset attributes and modes
CGI_Terminate()terminate CGI session
CGI_Clear_View_Surface(soft, hard)clear screen
CGI_Background_Colour(colour)set background colour
CGI CONTROL coordinate space control functions
CGI_VDC_Extent(first, second)define VDC extent
CGI_Device_Viewport(first, second)define device viewport
CGI_Device_Viewport_Specification_Units(units)
CGI_Device_Viewport_Specification_Mapping(isotropy, horizontal, vertical)
CGI_Clip_Rectangle(first, second)set clip rectangle
CGI_Clip_Indicator(indicator)specify clipping mode
CGI CONTROL error functions
CGI_Inquire_Supported_Error_Capabilities(depth)
inquire error stack size
CGI_Inquire_Error_Status(depth, oldest, lost)
inquire error state
CGI_Pop_Error_Stack(num, returned, reports)
pop error stack
CGI_Empty_Error_Stack()remove all reports from error stack
CGI CONTROL miscellaneous control functions
CGI_Message(action, text)print message
CGI_Application_Data(ident, data)set/get private data
CGI_Escape(ident, record)make use of non-standard features
CGI_Inquire_Escape(ident, record, output_record) inquire non-standard information
CGI CONTROL interrogation functions
CGI_Inquire_Device_Physical_Coordinate_System(bottom, top, width, height)
inquire device coordinate system
CGI CONTROL current state inquiry functions
CGI_Inquire_VDC_Extent(first, second)
CGI_Inquire_Device_Viewport(units, first, second)
CGI_Inquire_Device_Viewport_Specification_Units(units)
CGI_Inquire_Device_Viewport_Specification_Mapping(isotropy, horizontal,
    vertical)
CGI_Inquire_Clip_Rectangle(first, second)
CGI_Inquire_Clip_Indicator(indicator)
CGI INPUT input functions
CGI_Initialise_Input_Device(class, deviceIndex)
CGI_Release_Input_Device(class, deviceIndex)
terminate input actions
CGI_Set_Acknowledgement_State(class, deviceIndex, ackState)
set ack on/off
CGI_Set_Current_Value(class, deviceIndex, value)
CGI_Set_Echo_Data(class, deviceIndex, echoType, promptType, ackType,
    echoAreaFirst, echoAreaSecond, echoDataRecord)
CGI_Set_Echo_State(class, deviceIndex, echoState)
set echo on/off
CGI_Set_Input_Device_Data(class, deviceIndex, deviceDataRecord)
update data
CGI_Set_Prompt_State(class, deviceIndex, promptState)
set prompt on/off
CGI_Request(class, deviceIndex, timeout, reqStatus, validStatus,
    trigger, value)
request data
CGI_Sample(class, deviceIndex, value, validityStatus)
get current value
CGI_Initialise_Echo_Request(class, deviceIndex, timeout)
CGI_Echo_Request(class, deviceIndex, reqStatus, validStatus,
    trigger, value)
CGI INPUT interrogation functions
CGI_Inquire_Input_Capabilities(error, numChoiceDev, numLocatorDev,
    numPickDev, numStringDev, numStrokeDev, numValuatorDev, numTriggers)
inquire virtual device description
CGI_Inquire_Capabilities(class, deviceIndex, error, echoTypes, promptTypes,
    acknowledgementTypes, inputMaxima)
inquire logical device description
CGI INPUT inquiry functions
CGI_Inquire_Input_Device_State_List(class, deviceIndex, error, deviceState,
    deviceDataRecord, promptState, promptType, ackState, ackType,
    echoState, echoType, echoAreaFirst, echoAreaSecond, echoDataRecord, associatedTriggers)
inquire logical device state list
CGI_Inquire_Input_Device_State(class, deviceIndex, error, deviceState)
CGI_Inquire_Input_Device_Data(class, deviceIndex, error, deviceDataRecord)
CGI_Inquire_Prompt_State(class, deviceIndex, error, promptState)
CGI_Inquire_Acknowledgement_State(class, deviceIndex, error, ackState)
CGI_Inquire_Echo_Data(class, deviceIndex, error, ackType, promptType,
    echoType, echoAreaFirst, echoAreaSecond, echoDataRecord)
CGI_Inquire_Echo_State(class, deviceIndex, error, echoState)
CGI_Inquire_Associated_Triggers(class, deviceIndex, error,
    associatedTriggers)
CGI OUTPUT graphical primitive functions
CGI_Polyline(np, pointList)draw polyline
CGI_Disjoint_Polyline(np, pointList)draw disjoint polyline
CGI_Circular_Arc_3_Point(startingPoint, intermediatePoint, endingPoint)
draw arc specified by 3 points
CGI_Circular_Arc_Center(center, startVector, endVector, radius)
draw arc specified by center and vectors
CGI_Elliptical_Arc(center, firstCDPendp, secondCDPendp, startVector,
    endVector)
draw elliptical arc
CGI_Polymarker(np, pointlist)draw polymarker
CGI_Text(point, flag, string)print text
CGI_Restricted_Text(extentx, extenty, point, flag, string)
print text within specified area
CGI_Append_Text(flag, string)append text
CGI_Polygon(np, pointList)draw polygon
CGI_Polygon_Set(np, fplist)draw set of polygon
CGI_Rectangle(point1, point2)draw rectangle
CGI_Circle(center, radius)draw circle
CGI_Circular_Arc_3_Point_Close(startingPoint, intermediatePoint,
    endingPoint, closeType)
draw pie or chord specified by 3 points
CGI_Circular_Arc_Center_Close(center, startVector, endVector, radius,
    closeType)
draw pie or chord specified by center and vectors
CGI_Ellipse(center, firstCDPendp, secondCDPendp)
draw ellipse
CGI_Elliptical_Arc_Close(center, firstCDPendp, secondCDPendp,
    startVector, endVector, closeType)
CGI_Cell_Array(pointP, pointQ, pointR, nx, ny, localColourPrecision,
    cellColourSpecifiers)
draw cell array
CGI OUTPUT attribute functions
CGI_Line_Bundle_Index(index)set line bundle index
CGI_Line_Type(type)set line type (solid, dash, etc.)
CGI_Line_Width(width)
CGI_Line_Colour(specifier)
CGI_Line_Representation(index, type, width, colour)
set line bundle table
CGI_Marker_Bundle_Index(index)set marker bundle index
CGI_Marker_Type(type)set marker type (dot, cross, etc.)
CGI_Marker_Size(size)
CGI_Marker_Colour(specifier)
CGI_Marker_Representation(index, type, size, colour)
set marker bundle table
CGI_Text_Bundle_Index(index)set text bundle table
CGI_Text_Font_Index(index)
CGI_Character_Expansion_Factor(factor)
CGI_Character_Spacing(spacing)
CGI_Text_Colour(specifier)
CGI_Character_Height(height)
CGI_Character_Orientation(upVector, baseVector)
CGI_Text_Path(path)specify text path (up, down, etc.)
CGI_Text_Alignment(horizontalAlignment, verticalAlignment,
    continuousHorizontalAlignment, continuousVerticalAlignment)
set text alignment
CGI_Text_Representation(index, font, prec, spacing, exfactor, colour)
set text bundle table
CGI_Fill_Bundle_Index(index)
CGI_Interior_Style(style)specify how to fill
CGI_Fill_Colour(specifier)
CGI_Hatch_Index(index)set hatch index
CGI_Pattern_Index(index)set pattern index
CGI_Fill_Reference_Point(point)
CGI_Pattern_Table(index, nx, ny, localColourPrecision, pattern)
set pattern
CGI_Pattern_Size(heightVector, widthVector)
specify pattern size
CGI_Fill_Representation(index, interior, colour, hatch, pattern)
set fill bundle table
CGI_Edge_Bundle_Index(index)
CGI_Edge_Type(type)set edge type (same as line type)
CGI_Edge_Width(width)
CGI_Edge_Colour(specifier)
CGI_Edge_Visibility(flag)edge drawing on/off
CGI_Edge_Representation(index, type, width, colour)
set edge bundle table
CGI OUTPUT output & attribute control functions
CGI_Colour_Selection_Mode(mode)specify colour mode (index, direct)
CGI_Colour_Value_Extent(min, max)specify colour value range
CGI_Auxiliary_Colour(colour)set auxiliary colour
CGI_Transparency(trans)transparency on/off
CGI_Colour_Table(startingIndex, ncolour, colourlist)
set colour table
CGI_Line_Width_Specification_Mode(mode)
CGI_Edge_Width_Specification_Mode(mode)
CGI_Marker_Size_Specification_Mode(mode)
CGI_Aspect_Source_Flags(ASF_type, ASFvalue)
set aspect source flag
CGI_Font_List(nname, fontnamelist)set font
CGI OUTPUT inquiry functions
CGI_Inquire_Aspect_Source_Flag(type, value)
CGI_Inquire_Line_Bundle_Representation(index, type, widthSpecMode, width,
    colourSelectionMode, colour)
inquire line bundle table entry
CGI_Inquire_Line_Indices(size, nentry, rentry, definedIndices)
inquire defined line bundle indices
CGI_Inquire_Line_Individual_Attributes(type, widthSpecMode, width,
    colourSelectionMode, colour, index)
CGI_Inquire_Marker_Bundle_Representation(index, type, sizeSpecMode, size,
    colourSelectionMode, colour)
inquire marker bundle table entry
CGI_Inquire_Marker_Indices(size, nentry, rentry, definedIndices)
inquire defined marker bundle indices
CGI_Inquire_Marker_Individual_Attributes(type, sizeSpecMode, size,
    colourSelectionMode, colour, index)
CGI_Inquire_Fill_Bundle_Representation(index, interior,
    colourSelectionMode, colour, hatch, pattern)
inquire fill bundle table entry
CGI_Inquire_Fill_Indices(size, nentry, rentry, definedIndices)
inquire defined fill bundle indices
CGI_Inquire_Fill_Individual_Attributes(interior, colourSelectionMode,
    colour, hatch, pattern, refpoint, patternsize, index)
CGI_Inquire_Pattern_Indices(size, nentry, rentry, definedIndices)
inquire defined pattern indices
CGI_Inquire_Pattern_Table(index, row, column, colourSelectionMode,
    localColourPrecision, colourlist)
inquire pattern
CGI_Inquire_Edge_Bundle_Representation(index, type, widthSpecMode, width,
    colourSelectionMode, colour)
inquire edge bundle table entry
CGI_Inquire_Edge_Indices(size, nentry, rentry, definedIndices)
inquire defined edge indices
CGI_Inquire_Edge_Individual_Attributes(visibility, type, widthSpecMode,
    width, colourSelectionMode, colour, index)
CGI_Inquire_Text_Bundle_Representation(index, font, precision, exfactor,
    spacing, colourSelectionMode, colour)
inquire text bundle table entry
CGI_Inquire_Text_Indices(size, nentry, rentry, definedIndices)
inquire defined text indices
CGI_Inquire_Text_Individual_Attributes(charset, altcharset, index, font,
    precision, exfactor, spacing, colourSelectionMode, colour, charheight,
    upVector, baseVector, path, hor_align, ver_align, cont_hor_align,
    cont_ver_align)
CGI_Inquire_Colour_Table(index, nentry, rentry, value)
CGI_Inquire_Specification_Modes(lineWidthSpec, edgeWidthSpec,
    markerSizeSpec)
inquire size specification modes
CGI_Inquire_Colour_Selection_Mode(colourSelectionMode)
inquire colour selection mode
CGI_Inquire_Auxiliary_Colour_And_Transparency(trans, colourMode, auxColor)
CGI OUTPUT interrogation functions
CGI_Inquire_Supported_Colour(nsimulcolour, navailcolour, colourtblsupport,
    background, overwrite, monochrome)
CGI_Inquire_Closed_Figure_Support(nvert, edgeAttrChange)
CGI ECHO OUTPUT OPTION SET set functions
CGI_Set_Echo_Output_Data(inputClass, echoIndex, currentValue, ackType,
    promptType, echoType, echoAreaFirst, echoAreaSecond, echoDataRecord)
CGI_Set_Echo_Output_State(inputClass, echoIndex, echoState)
CGI_Set_Prompt_Output_State(inputClass, echoIndex, promptState)
CGI_Set_Acknowledgement_Output_State(inputClass, echoIndex, ackState)
CGI_Update_Echo_Output(inputClass, echoIndex, newValue)
CGI ECHO OUTPUT OPTION SET inquiry functions
CGI_Inquire_Echo_Output_Capabilities(maxEchoes, echoTypesSupported,
    promptTypesSupported, ackTypesSupported, maxStringLength, maxStrokePoints)
CGI_Inquire_Echo_Output_State_List(inputClass, echoIndex, currentValue,
    echoState, echoType, promptState, promptType, ackState, ackType,
    echoAreaFirst, echoAreaSecond, echoDataRecord)
CGI RASTER OPTION SET raster output functions
CGI_Pixel_Array(org_p, xcnt, ycnt, vxcnt1, vxcnt2, vycnt1, vycnt2,
    col_prec, colours)
display pixel array
CGI RASTER OPTION SET raster attribute functions
CGI_Mapped_Bitmap_Foreground_Colour(colour)
CGI RASTER OPTION SET raster control functions
CGI_Create_Bitmap(ext_p1, ext_p2, type, bm_idx)
CGI_Delete_Bitmap(bm_idx)
CGI_Select_Drawing_Bitmap(bm_idx)
CGI_Display_Bitmap(bm_idx)
CGI_Two_Operand_Bitblt(src_bm_idx, src_p, dest_p, xoff, yoff)
CGI_Tile_Two_Operand_Bitblt(pat_bm_idx, pat_p1, pat_p2, dest_p1, dest_p2)
CGI_Drawing_Mode(draw_mode)set raster operation function
CGI RASTER OPTION SET raster interrogation functions
CGI_Inquire_Displayable_Bitmaps(nbm)
CGI_Inquire_Bitmap_Formats(bm_fmts)
CGI_Inquire_Preferred_Bitblt_Pattern_Size(ext_x, ext_y)
CGI_Inquire_Supported_Drawing_Mode(transp, draw_mode, stat)
CGI RASTER OPTION SET raster inquiry functions
CGI_Inquire_Current_Drawing_Mode(draw_mode)
CGI_Inquire_Drawing_Bitmap(bm_idx)
CGI_Inquire_Display_Bitmap(bm_idx)
CGI_Inquire_Mapped_Bitmap_Foreground_Colour(colour)
CGI_Inquire_Pixel_Array(org_p, xcnt, ycnt, vxcnt1, vxcnt2, vycnt1, vycnt2,
    col_prec, colours)

IMPLEMENTATION

Current implementation of CGI on NEWS provides library functions which support C language program interface and uses device drivers ( fb(4), mouse(4) ) to access graphics resources on NEWS.

CGI library function names are formed by concatenating words used for abstract function names, preceded by ‘CGI_’. For example, the abstract function (specified in the CGI working document)

CIRCULAR ARC CENTER CLOSE

becomes

CGI_Circular_Arc_Center_Close

For the list of C function names and parameter interface, see ‘CGI Function Reference Manual’.

RESTRICTION

Current implementation of CGI on NEWS has some restrictions as follows.
The pattern area specified by CGI_Pattern_Size() and cell array area must be rectangular.
Text functions don’t accept any control characters.
The VALUATOR, STROKE and PICK input classes are not supported.

FILES

/usr/sony/demo/cgi/CGI demo program directory
/usr/sony/doc/cgi/CGI documentation directory

Museum

Related Articles