Jump to content

GpiOpenSegment: Difference between revisions

From EDM2
No edit summary
No edit summary
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This function opens a segment with the specified identification number.
==Syntax==
==Syntax==
  GpiOpenSegment(hps, lSegment)
  GpiOpenSegment(hps, lSegment)
Line 4: Line 5:
==Parameters==
==Parameters==
;hps (HPS) - input:Presentation-space handle.
;hps (HPS) - input:Presentation-space handle.
;lSegment (LONG) - input:
;lSegment (LONG) - input:Segment identifier.
:Must be zero or a positive number.


==Returns==
==Returns==
Line 10: Line 12:
*TRUE - Successful completion
*TRUE - Successful completion
*FALSE - Error occurred.
*FALSE - Error occurred.
==Errors==
Possible returns from WinGetLastError
;PMERR_INV_HPS (0x207F):An invalid presentation-space handle was specified.
;PMERR_PS_BUSY (0x20F4):An attempt was made to access the presentation space from more than one thread simultaneously.
;PMERR_INV_SEG_NAME (0x20C8):An invalid segment identifier was specified.
;PMERR_INV_MICROPS_FUNCTION (0x20A1):An attempt was made to issue a function that is invalid in a micro presentation space.
;PMERR_ALREADY_IN_SEG (0x2004):An attempt was made to open a new segment while an existing segment bracket was already open.
;PMERR_PATH_INCOMPLETE (0x20EC):An attempt was made to open or close a segment either directly or during segment drawing, or to issue GpiAssociate while there is an open path bracket. ;PMERR_AREA_INCOMPLETE (0x2005):One of the following has occurred: o A segment has been opened, closed, or drawn.
:* GpiAssociate was issued while an area bracket was open.
:* A drawn segment has opened an area bracket and ended without closing it.
;PMERR_INV_MODE_FOR_REOPEN_SEG (0x20A5):An attempt was made to reopen an existing segment while the drawing mode was set to DM_DRAW or DM_DRAWANDRETAIN.
;PMERR_DYNAMIC_SEG_ZERO_INV (0x2029):An attempt was been made to open a dynamic segment with a segment identifier of zero.
;PMERR_INV_MODE_FOR_OPEN_DYN (0x20A4):An attempt was made to open a segment with the ATTR_DYNAMIC segment set, while the drawing mode was set to DM_DRAW or DM_DRAWANDRETAIN. ;PMERR_UNCHAINED_SEG_ZERO_INV (0x2108):An attempt was made to open segment with segment identifier zero and the ATTR_CHAINED segment attribute not specified.
==Remarks==
A segment is a way of grouping graphics primitives.
If the current drawing mode is retain or draw-and-retain (see [[GpiSetDrawingMode]]), the following occurs:
* If a nonzero identifier is given, and if a segment with the specified identifier does not already exist, a new retained segment is created. If one does already exist, it is reopened in retain mode (with the element pointer set to 0), but is an error in draw-and-retain mode.
* If an identifier of 0 is given, a new retained segment is created, regardless of whether one with a 0 identifier already exists. There can be more than one segment with an identifier of 0, but such segments can never subsequently be referenced by identifier. When they have been created, they continue to exist until all segments are deleted. Zero segments must be chained and cannot be defined as dynamic.
If the current drawing mode is draw, a new nonretained segment is started. No check is made against any possible retained segment identifiers. The current attributes are set to default values (subject to the ATTR_FASTCHAIN segment attribute; see below).
The initial attributes of the segment are as set by [[GpiSetInitialSegmentAttrs]]. The attributes may subsequently be changed with [[GpiSetSegmentAttrs]] (except for a segment with an identifier of 0). It is an error to try to open a new segment with a drawing mode of draw or draw-and-retain, with the ATTR_DYNAMIC segment attribute.
This function causes a segment bracket to be started. While the bracket is in effect, any primitive and attribute functions are considered to be part of the segment, and are stored in it if the drawing mode is retain or draw-and-retain. The bracket is terminated by a [[GpiCloseSegment]]. It is an error if [[GpiOpenSegment]] is issued when a segment is already open.
The following actions occur when drawing of a chained segment is started (either as it is passed across the API in draw or draw-and-retain, or as it is found during a draw operation):
* Current attributes and arc parameters are reset to default values. The current tag is reset to its default value.
* Current model transform is reset to unity.
* Current position is set to (0,0).
* The current clip path is set so as to cause no clipping.
* The current viewing limits are reset to their default values.
* The current viewing transform is set either to the value last set by [[GpiSetViewingTransformMatrix]], or to the default value if no [[GpiSetViewingTransformMatrix]] function has been issued.
If the segment has the ATTR_FASTCHAIN attribute, the application should not depend upon whether or not these operations are performed. This avoids complications when interchanging picture data with other implementations. Note: The current clip region is not changed by this function.
If any primitive/attribute calls are issued immediately before this function (that is, outside a segment bracket), then any currently open area, path, or element brackets are terminated, as described for [[GpiCloseSegment]], before the new segment is opened.
If the segment being defined is to be called from another segment (see [[GpiCallSegmentMatrix]]), ensure that the viewing transform (see [[GpiSetViewingTransformMatrix]]) is unity before first opening the segment.
The maximum number of retained segments allowed for a given presentation space at any time is 16378.
==Example Code==
<pre>
#define INCL_GPISEGMENTS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>
HPS    hps;      /*  Presentation-space handle. */
LONG    lSegment;  /*  Segment identifier. */
BOOL    rc;        /*  Success indicator. */
rc = GpiOpenSegment(hps, lSegment);
</pre>
This example uses the GpiOpenSegment to create a new segment. The segment is subsequently drawn by using the GpiDrawSegment function.
<pre>
#define INCL_GPISEGMENTS        /* Segment functions            */
#include <os2.h>
HPS hps;                /* presentation space handle            */
POINTL ptlStart = { 0, 0 }; /* first vertex                    */
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices  */
GpiOpenSegment(hps, 1L);      /* opens the segment            */
GpiMove(hps, &ptlStart);      /* moves to starting point (0,0) */
GpiPolyLine(hps, 3L, ptlTriangle);/* draws triangle            */
GpiCloseSegment(hps);          /* closes the segment            */
GpiDrawSegment(hps, 1L);
</pre>
==Related Functions==
* [[GpiCallSegmentMatrix]]
* [[GpiCloseSegment]]
* [[GpiCorrelateSegment]]
* [[GpiDeleteSegment]]
* [[GpiDeleteSegments]]
* [[GpiDrawSegment]]
* [[GpiErrorSegmentData]]
* [[GpiQueryInitialSegmentAttrs]]
* [[GpiQuerySegmentAttrs]]
* [[GpiQuerySegmentNames]]
* [[GpiQuerySegmentPriority]]
* [[GpiSetInitialSegmentAttrs]]
* [[GpiSetSegmentAttrs]]
* [[GpiSetSegmentPriority]]
* [[GpiSetViewingTransformMatrix]]


[[Category:Gpi]]
[[Category:Gpi]]
[[Category:WorkToDo]]

Latest revision as of 04:49, 7 April 2025

This function opens a segment with the specified identification number.

Syntax

GpiOpenSegment(hps, lSegment)

Parameters

hps (HPS) - input
Presentation-space handle.
lSegment (LONG) - input
Segment identifier.
Must be zero or a positive number.

Returns

rc (BOOL) - returns
Success indicator.
  • TRUE - Successful completion
  • FALSE - Error occurred.

Errors

Possible returns from WinGetLastError

PMERR_INV_HPS (0x207F)
An invalid presentation-space handle was specified.
PMERR_PS_BUSY (0x20F4)
An attempt was made to access the presentation space from more than one thread simultaneously.
PMERR_INV_SEG_NAME (0x20C8)
An invalid segment identifier was specified.
PMERR_INV_MICROPS_FUNCTION (0x20A1)
An attempt was made to issue a function that is invalid in a micro presentation space.
PMERR_ALREADY_IN_SEG (0x2004)
An attempt was made to open a new segment while an existing segment bracket was already open.
PMERR_PATH_INCOMPLETE (0x20EC)
An attempt was made to open or close a segment either directly or during segment drawing, or to issue GpiAssociate while there is an open path bracket. ;PMERR_AREA_INCOMPLETE (0x2005):One of the following has occurred: o A segment has been opened, closed, or drawn.
  • GpiAssociate was issued while an area bracket was open.
  • A drawn segment has opened an area bracket and ended without closing it.
PMERR_INV_MODE_FOR_REOPEN_SEG (0x20A5)
An attempt was made to reopen an existing segment while the drawing mode was set to DM_DRAW or DM_DRAWANDRETAIN.
PMERR_DYNAMIC_SEG_ZERO_INV (0x2029)
An attempt was been made to open a dynamic segment with a segment identifier of zero.
PMERR_INV_MODE_FOR_OPEN_DYN (0x20A4)
An attempt was made to open a segment with the ATTR_DYNAMIC segment set, while the drawing mode was set to DM_DRAW or DM_DRAWANDRETAIN. ;PMERR_UNCHAINED_SEG_ZERO_INV (0x2108):An attempt was made to open segment with segment identifier zero and the ATTR_CHAINED segment attribute not specified.

Remarks

A segment is a way of grouping graphics primitives.

If the current drawing mode is retain or draw-and-retain (see GpiSetDrawingMode), the following occurs:

  • If a nonzero identifier is given, and if a segment with the specified identifier does not already exist, a new retained segment is created. If one does already exist, it is reopened in retain mode (with the element pointer set to 0), but is an error in draw-and-retain mode.
  • If an identifier of 0 is given, a new retained segment is created, regardless of whether one with a 0 identifier already exists. There can be more than one segment with an identifier of 0, but such segments can never subsequently be referenced by identifier. When they have been created, they continue to exist until all segments are deleted. Zero segments must be chained and cannot be defined as dynamic.

If the current drawing mode is draw, a new nonretained segment is started. No check is made against any possible retained segment identifiers. The current attributes are set to default values (subject to the ATTR_FASTCHAIN segment attribute; see below).

The initial attributes of the segment are as set by GpiSetInitialSegmentAttrs. The attributes may subsequently be changed with GpiSetSegmentAttrs (except for a segment with an identifier of 0). It is an error to try to open a new segment with a drawing mode of draw or draw-and-retain, with the ATTR_DYNAMIC segment attribute.

This function causes a segment bracket to be started. While the bracket is in effect, any primitive and attribute functions are considered to be part of the segment, and are stored in it if the drawing mode is retain or draw-and-retain. The bracket is terminated by a GpiCloseSegment. It is an error if GpiOpenSegment is issued when a segment is already open.

The following actions occur when drawing of a chained segment is started (either as it is passed across the API in draw or draw-and-retain, or as it is found during a draw operation):

  • Current attributes and arc parameters are reset to default values. The current tag is reset to its default value.
  • Current model transform is reset to unity.
  • Current position is set to (0,0).
  • The current clip path is set so as to cause no clipping.
  • The current viewing limits are reset to their default values.
  • The current viewing transform is set either to the value last set by GpiSetViewingTransformMatrix, or to the default value if no GpiSetViewingTransformMatrix function has been issued.

If the segment has the ATTR_FASTCHAIN attribute, the application should not depend upon whether or not these operations are performed. This avoids complications when interchanging picture data with other implementations. Note: The current clip region is not changed by this function.

If any primitive/attribute calls are issued immediately before this function (that is, outside a segment bracket), then any currently open area, path, or element brackets are terminated, as described for GpiCloseSegment, before the new segment is opened.

If the segment being defined is to be called from another segment (see GpiCallSegmentMatrix), ensure that the viewing transform (see GpiSetViewingTransformMatrix) is unity before first opening the segment.

The maximum number of retained segments allowed for a given presentation space at any time is 16378.


Example Code

#define INCL_GPISEGMENTS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS     hps;       /*  Presentation-space handle. */
LONG    lSegment;  /*  Segment identifier. */
BOOL    rc;        /*  Success indicator. */

rc = GpiOpenSegment(hps, lSegment);

This example uses the GpiOpenSegment to create a new segment. The segment is subsequently drawn by using the GpiDrawSegment function.

 
#define INCL_GPISEGMENTS        /* Segment functions            */
#include <os2.h>

HPS hps;                /* presentation space handle            */
POINTL ptlStart = { 0, 0 }; /* first vertex                     */
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices  */

GpiOpenSegment(hps, 1L);       /* opens the segment             */
GpiMove(hps, &ptlStart);       /* moves to starting point (0,0) */
GpiPolyLine(hps, 3L, ptlTriangle);/* draws triangle             */
GpiCloseSegment(hps);          /* closes the segment            */

GpiDrawSegment(hps, 1L);

Related Functions