.\"##
.\" $XConsortium: p402,v 5.3 94/04/17 20:59:08 hersh 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 "UPDATE WORKSTATION" 3P "29 February 1991"
.SH NAME
UPDATE WORKSTATION \- execute deferred workstation actions and optionally correct the display
.IX "Workstations" "UPDATE WORKSTATION"
.IX "Regeneration" "UPDATE WORKSTATION"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pupd_ws ( ws, regen_flag )
Pint	ws;	\fIworkstation identifier\fP
Pregen_flag	regen_flag;	\fIwhen to do the regeneration\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, * )
.SH DESCRIPTION
.SS Purpose
\s-2UPDATE WORKSTATION\s+2 completes any actions in progress on the
specified workstation.
Then, depending on the value of the \fIregeneration flag\fP
and the correctness of the workstation's display,
the display is regenerated to make it \s-2PVISUAL_ST_CORRECT\s+2.
.SS C Input Parameters
.IP \fIws\fP
The identifier of the workstation to be updated.
.IP \fIregen_flag\fP
The regeneration flag controls whether the display should be made
entirely correct.
.\"	Pregen is defined in \fIphigs.h\fP.
Valid values are:
.sp .4
.ta 1.5i 
.nf
PFLAG_PERFORM	\fIMake picture \s-2PVISUAL_ST_CORRECT\s+2 if it is not\fP
PFLAG_POSTPONE	\fIPostpone regeneration; only complete deferred workstation actions\fP
.fi
.SS Execution
\s-2UPDATE WORKSTATION\s+2
always initiates transmission of any data buffered from previous actions on the
specified workstation, without first clearing the display surface.
.LP
Then \s-2UPDATE WORKSTATION\s+2 may regenerate the display,
depending on the value of the \fIregeneration flag\fP parameter
and the correctness of the workstation's display.
If \fIregeneration flag\fP is set to \s-2PFLAG_PERFORM\s+2,
and the workstation's display is not entirely \s-2PVISUAL_ST_CORRECT\s+2,
.\"OK:	(i.e., it is either \s-2PVISUAL_ST_SIMULATED\s+2 or \s-2PVISUAL_ST_DEFER\s+2),
\s-2UPDATE WORKSTATION\s+2 regenerates the display, performing
the following actions:
.\"
.\"		Actions must match those for REDRAW ALL STRUCTURES!
.\"
.sp
.in +0.5i
.ta +0.2i
.ti -0.2i
1.	If the workstation's display is not empty,
then the display surface is cleared.
.sp
.ti -0.2i
2.	For every view representation in the View workstation state list,
if the \fIview transformation update state\fP is \s-2PUPD_PEND\s+2,
the current view representation is loaded from the \fIrequested\fP view
representation, and the update state is set to \s-2PUPD_NOT_PEND\s+2.
.sp
.ti -0.2i
3.	If the \fIworkstation transformation update state\fP is \s-2PUPD_PEND\s+2,
the \fIcurrent workstation window\fP, and \fIcurrent workstation viewport\fP
are loaded with the \fIrequested\fP values for each,
and the update state is set to \s-2PUPD_NOT_PEND\s+2.
.sp
.ti -0.2i
4.	If the workstation's \fI\s-2HLHSR\s+2 update state\fP
is \s-2PUPD_PEND\s+2, the \fIcurrent \s-2HLHSR\s+2 mode\fP is updated
to the value of the \fIrequested \s-2HLHSR\s+2 mode\fP; and
the update state is set to \s-2PUPD_NOT_PEND\s+2.
.sp
.ti -0.2i
5.	All structure networks posted for this workstation are redisplayed
in their priority order.
.sp
.ti -0.2i
6.	The workstation's \fIstate of visual representation\fP is set to
\s-2PVISUAL_ST_CORRECT\s+2.
.DT
.LP
The workstation's state of visual representation indicates
if the display is \s-2PVISUAL_ST_CORRECT\s+2, \s-2PVISUAL_ST_SIMULATED\s+2, or \s-2PVISUAL_ST_DEFER\s+2.
\s-2INQUIRE DISPLAY UPDATE STATE\s+2 returns the
workstation's \fIdisplay surface empty\fP and state of visual representation
state list entries.
Normally, the traversal in step 5 causes
the display surface empty workstation state to become \s-2PSTAT_NOTEMPTY\s+2.
(If all the posted structures are empty, or contain elements but no
output primitive elements, the display surface empty may be
\s-2PSTRUCT_STATUS_EMPTY\s+2 or \s-2PSTAT_NOTEMPTY\s+2.)
.LP
\s-2UPDATE WORKSTATION\s+2 performs the same sequence of actions
as \s-2REDRAW ALL STRUCTURES\s+2 when:
.sp .5v
.in +0.5i
.ta +0.2i
.ti -0.2i
\(bu	\fIregeneration flag\fP is \s-2PFLAG_PERFORM\s+2.
.sp .5v
.ti -0.2i
\(bu	The workstation's state of visual representation
is \s-2PVISUAL_ST_DEFER\s+2 or \s-2PVISUAL_ST_SIMULATED\s+2.
.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)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "INQUIRE DISPLAY UPDATE STATE (3P)"
.SM "SET DISPLAY UPDATE STATE (3P)"
.SM "REDRAW ALL STRUCTURES (3P)"
.fi