.\"##
.\" $XConsortium: p325,v 5.2 94/04/17 20:58:12 rws Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.TH "SET HLHSR MODE" 3P "29 February 1991"
.SH NAME
SET HLHSR MODE \- enable or disable hidden line and hidden surface removal on a workstation
.IX "HLHSR" "SET HLHSR MODE"
.IX "Z-buffering" "SET HLHSR MODE"
.IX "Hidden Line/Hidden Surface Removal" "SET HLHSR MODE"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_hlhsr_mode ( ws, mode )
Pint	ws;		\fIworkstation identifier\fP
Pint	mode;	\fIHLHSR mode\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
The \s-2SET HLHSR MODE\s+2 requests a certain Hidden Line and 
Hidden Surface Removal
(\s-2HLHSR\s+2) mode of the
workstation.
The workstation's current \s-2HLHSR\s+2 mode 
enables or disables \s-2HLHSR\s+2
for a workstation.
The current \s-2HLHSR\s+2 identifier
from the structure network
is used in conjunction with
the \s-2HLHSR\s+2 mode on the workstation during traversal.
.SS C Input Parameters
.IP \fIws\fP
The identifier of the workstation whose \s-2HLHSR\s+2 mode is being set.
.IP \fImode\fP
The \s-2HLHSR\s+2 mode value.  Presently defined values are:
.nf
.sp
.ta .5i +\w'0     'u +\w'PHIGS_HLHSR_MODE_LINE_ONLY     'u
0	PHIGS_HLHSR_MODE_NONE	\fIDisable Z-buffering\fP
1	PHIGS_HLHSR_MODE_ZBUFF	\fIEnable Z-buffering\fP
2	PHIGS_HLHSR_MODE_PAINTERS
3	PHIGS_HLHSR_MODE_SCANLINE
4	PHIGS_HLHSR_MODE_LINE_ONLY
.sp
.fi
.SS Execution
If the requested \s-2HLHSR\s+2 mode value is supported
on the specified workstation, then
\s-2SET HLHSR MODE\s+2 immediately sets the requested \s-2HLHSR\s+2 mode
entry in the PHIGS workstation state list to the specified mode.
The effect of calling \s-2SET HLHSR MODE\s+2 is not visible
until the \fIrequested\fP \s-2HLHSR\s+2 mode replaces the \fIcurrent\fP
\s-2HLHSR\s+2 mode.
The time at which this occurs
depends on the workstation's display update state.
.LP
This assignment is performed immediately
and the \s-2HLHSR\s+2 update state is set to \fINot Pending\fP
if any one of the following is true:
.sp .5v
.in +0.5i
.ta +0.2i
.ti -0.2i
\(bu	The workstation display update state allows update.
.sp .5v
.ti -0.2i
\(bu	The workstation modification mode is any value other than
\fINo Immediate Visual Effect\fP,
and the dynamic modification accepted for \s-2HLHSR\s+2 mode
entry in the workstation description table is set to \fIImmediate\fP.
.sp .5v
.ti -0.2i 
\(bu	The \fIdisplay space empty\fP status in the workstation
state list is \s-2EMPTY\s+2.
.LP
Otherwise, the \s-2HLHSR\s+2 update state is set to \fIPending\fP
and the requested \s-2HLHSR\s+2 mode will not replace the 
current \s-2HLHSR\s+2 mode until
the next time the workstation is updated.
The \s-2HLHSR\s+2 update state will be set to \fINot Pending\fP at that time.
.LP
During traversal, the workstation's current \s-2HLHSR\s+2 mode entry
and the primitive's current \s-2HLHSR\s+2 identifier
attribute are both checked.
.SH ERRORS
.IP 003
Ignoring function, function requires state (\s-2PHOP, WSOP, *, *\s+2)
.IP 054
Ignoring function, the specified workstation is not open
.IP 059
Ignoring function, the specified workstation does not have output capability
(that is, the workstation category is neither \s-2OUTPUT\s+2,
\s-2OUTIN\s+2, nor \s-2MO\s+2) 
.IP 111
Ignoring function, the specified \s-2HLHSR\s+2 mode is not available
on the specified workstation
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET HLHSR IDENTIFIER (3P)"
.SM "INQUIRE HLHSR MODE (3P)"
.fi