Jump to content

VioSavRedrawWait: Difference between revisions

From EDM2
Ak120 (talk | contribs)
Ak120 (talk | contribs)
mNo edit summary
Line 1: Line 1:
==Description==
Notifies a graphics mode application when it must save or redraw its screen image.
Notifies a graphics mode application when it must save or redraw its screen image.


==Syntax==
==Syntax==
<PRE>
VioSavRedrawWait (SaveRedrawIndic, NotifyType, VioHandle)
#define INCL_VIO
#include <os2.h>


ULONG    SaveRedrawIndic;  /*  Save/redraw indicator. */
PULONG    NotifyType;      /*  Notify type (returned). */
HVIO      VioHandle;        /*  Reserved.  Must be 0. */
APIRET    rc;              /*  Return code. */
rc = VioSavRedrawWait(SaveRedrawIndic, NotifyType, VioHandle);
</PRE>
==Parameters==
==Parameters==
; SaveRedrawIndic (ULONG) - input : Save/redraw indicator.
;SaveRedrawIndic (ULONG) - input : Save/redraw indicator.
Indicates which events the application is waiting for:
:Indicates which events the application is waiting for:
 
:0 - The session manager notifies the application for both save and redraw operations.  
  Value        Definition
:1 - The session manager notifies the application for redraw operations only.  
    0       The session manager notifies the application for both save and redraw operations.  
    1       The session manager notifies the application for redraw operations only.  


; NotifyType (PULONG) - output : Notify type (returned).
; NotifyType (PULONG) - output : Notify type (returned).
Address that specifies the operation to be performed by the application upon return from VioSavRedrawWait:
Address that specifies the operation to be performed by the application upon return from VioSavRedrawWait:
 
Value      Definition  
                Value      Definition  
0      Save screen image.  
                  0      Save screen image.  
1      Restore screen image.  
                  1      Restore screen image.  


; VioHandle (HVIO) - input : Reserved. Must be 0.
; VioHandle (HVIO) - input : Reserved. Must be 0.
Line 34: Line 20:
==Return Code==
==Return Code==
  rc (APIRET) - returns
  rc (APIRET) - returns
VioSavRedrawWait returns one of the following values:
VioSavRedrawWait returns one of the following values:
* 0    NO_ERROR  
* 0    NO_ERROR  
* 421  ERROR_VIO_INVALID_PARMS  
* 421  ERROR_VIO_INVALID_PARMS  
Line 60: Line 44:
An application's VioSavRedrawWait thread might be notified to perform a restore before it is notified to perform a save. This happens if the application was running in the background the first time it issued VioSavRedrawWait. The return from this function call provides the notification. The thread that issues the call performs the save or redraw and then reissues VioSavRedrawWait to wait until its screen image must be saved or redrawn again.
An application's VioSavRedrawWait thread might be notified to perform a restore before it is notified to perform a save. This happens if the application was running in the background the first time it issued VioSavRedrawWait. The return from this function call provides the notification. The thread that issues the call performs the save or redraw and then reissues VioSavRedrawWait to wait until its screen image must be saved or redrawn again.


==Example Code==
[[Category:Vio]]
<PRE>
 
</PRE>
==Related Functions==
* [[OS2 API:CPI:
 
 
[[Category:The OS/2 API Project]]

Revision as of 19:36, 26 February 2017

Notifies a graphics mode application when it must save or redraw its screen image.

Syntax

VioSavRedrawWait (SaveRedrawIndic, NotifyType, VioHandle)

Parameters

SaveRedrawIndic (ULONG) - input
Save/redraw indicator.
Indicates which events the application is waiting for:
0 - The session manager notifies the application for both save and redraw operations.
1 - The session manager notifies the application for redraw operations only.
NotifyType (PULONG) - output
Notify type (returned).

Address that specifies the operation to be performed by the application upon return from VioSavRedrawWait:

Value       Definition 
0      Save screen image. 
1      Restore screen image. 
VioHandle (HVIO) - input
Reserved. Must be 0.

Return Code

rc (APIRET) - returns

VioSavRedrawWait returns one of the following values:

  • 0 NO_ERROR
  • 421 ERROR_VIO_INVALID_PARMS
  • 422 ERROR_VIO_FUNCTION_OWNED
  • 423 ERROR_VIO_RETURN
  • 430 ERROR_VIO_ILLEGAL_DURING_POPUP
  • 436 ERROR_VIO_INVALID_HANDLE

Remarks

The OS/2 operating system uses VioSavRedrawWait to notify a graphics-mode application to save or restore its screen image at screen switch time. The application in the outgoing foreground session is notified to perform a save. The application in the incoming foreground session is notified to perform a restore. The application must perform the action requested and immediately reissue VioSavRedrawWait. When an application performs a save, it saves its physical display buffer, video mode, and any other information the application needs to completely redraw its screen at restore time.

Only one process per session can issue VioSavRedrawWait. The process that first issues it becomes the owner of the function.

A text-mode application must issue VioSavRedrawWait only if the application writes directly to the registers on the display adapter. Assuming VioSavRedrawWait is not issued by a text-mode application, the OS/2 operating system performs the required saves and restores.

An application that issues VioSavRedrawWait might also need to issue VioModeWait. This would allow the application to be notified when it must restore its mode at the completion of an application or hard-error pop-up. See VioModeWait for more information. Two application threads would be required to perform these operations, in this case.

At the time a VioSavRedrawWait thread is notified, the session is in transition to or from the background. Although the session's official status is background, any selector to the physical display buffer previously obtained by the VioSavRedrawWait process (through VioGetPhysBuf) is valid, at this time. The physical display buffer must be accessed without issuing VioScrLock. Because the session's official status is background, any thread waits if it issues VioScrLock with the "wait if unsuccessful" option.

An application containing a VioSavRedrawWait thread should be designed so that the process does not cause any hard errors while the VioSavRedrawWait thread is running; otherwise, a system lockout might occur.

An application's VioSavRedrawWait thread might be notified to perform a restore before it is notified to perform a save. This happens if the application was running in the background the first time it issued VioSavRedrawWait. The return from this function call provides the notification. The thread that issues the call performs the save or redraw and then reissues VioSavRedrawWait to wait until its screen image must be saved or redrawn again.