R_ShowPCX()
 Shows a PCX-file on EGA/VGA/SuperVGA screens
------------------------------------------------------------------------------

 Syntax
        nRet := R_ShowPCX ( cPCXFile [, nYPos [, nXPos [, cDriver ] ] ] )

 Parameters
        cPCXFile        Filespec of the PCX-file to be examined
                        Format  : [drive:][\path\]filename.PCX
                        Example : C:\PICTURES\TREE.PCX
                        The extension (.PCX) may not be omitted !

        nYPos           Vertical screen position of the upper left corner
                        of the display area (in pixels).
                        If omitted the picture will be CENTRED VERTICALLY.

        nXPos           Horizontal screen position of the upper left corner
                        of the display area (in pixels).
                        If omitted the picture will be CENTRED HORIZONTALLY.

        cDriver         Filespec of the RPCXLib SuperVGA driver file.
                        Format  : [drive:][\path\]filename.ext

                        When a picture should be displayed in SuperVGA mode
                        the function R_ShowPCX must be able to locate the
                        SuperVGA driver file.
                        This file is included in the RPCXLib package and is
                        called RPCXLib.GDR.

                        If the driver file is not located in the current
                        DOS-directory this parameter should be used to
                        indicate where the driver file can be found.

 Returns
        nRet            Return code of R_ShowPCX()

                        The values and descriptions of this return code are
                        defined in RPCXLib.CH :

                         0 = PL_OKAY                    Okay
                         1 = PL_INVALID_PARAMETER       Invalid parameter
                                                        passed
                         2 = PL_OPEN_PCX                Error opening PCX-file
                         3 = PL_READ_PCX                Error reading PCX-file
                         4 = PL_NO_PCXFILE              File is no valid
                                                        PCX-file
                         5 = PL_INVALID_BPP             Invalid number of
                                                        Bits-Per-Pixel
                         6 = PL_INVALID_DIM             PCX-file has invalid
                                                        dimensions (> 640x480)
                         7 = PL_UNKNOWN_SVGA            Unknown SuperVGA card
                         8 = PL_OPEN_DRIVER             Error OPENING
                                                        RPCXLib.GDR driver
                         9 = PL_READ_DRIVER             Error READING
                                                        RPCXLib.GDR driver
                        10 = PL_SVGA_NOTSUPPORTED       SuperVGA-card not
                                                        supported (yet)
                        11 = PL_BUFFER_MEMORY           Not enough memory
                                                        for internal buffer

 Description
        R_ShowPCX() displays a PCX-file on a specific screen location.
        This function is perfect to show Company Logo's, Graphs,
        Wallpapers etc.

        The function chooses the most suitable video mode depending
        on the dimensions and number of colours of the picture to show.
        When needed the appropriate SuperVGA driver is loaded
        automatically.

        The next scheme shows the relationship between the dimension of
        the picture and the adapter that will be used :


                                      PCX-file
                                         |
                          +-----------------------------+
                          |                             |
                       16 colours                   256 colours
                  +--------------+              +--------------+
                  |              |              |              |
           <= 640 x 350   <= 640 x 480   <= 320 x 200   <= 640 x 480
                 EGA            VGA            VGA         SuperVGA 


        After the picture is displayed the R_ShowPCX() returns to the
        calling program while leaving the picture on the screen (the
        graphic video remains active).
        The calling program should take further action : for example
        wait for a keypress (with the INKEY()-function). When a key
        is pressed by the user the original video mode (TEXTMODE) should
        be restored using the R_VMSet()-function.
        This principle is demonstrated in the following example.

 Example
        && Shows a PCX-file PICTURE.PCX on the screen
        && on position (y,x) = (10,50)

        *-- RPCXLib definitions
        #include "RPCXLib.CH"

        *-- Return code R_ShowPCX()
        LOCAL       nRet

        *-- Array with error messages
        LOCAL       aPCXErrors := PL_ERRMSG

        *-- Save the actual video mode
        LOCAL       nVidMode   := R_VMGet ()

        [...]

        nRet := R_ShowPCX ( 'PICTURE.PCX', 10, 50 )

        IF nRet = PL_OKAY
                *-- Picture displayed, still on the screen

                *-- Wait for a keypress ... (max 10 seconds)
                Inkey ( 10 )

                *-- Restore video mode
                R_VMSet ( nVidMode )

        ELSE
                *-- Oops, error while displaying the picture

                *-- Display the error message
                ALERT ( 'Error R_ShowPCX() : ' + aPCXErrors [nRet] )

        ENDIF

        && Continuation of the program
        [...]


        See for more detailed examples PCXDemo.PRG.