View source for GpiPlayMetaFile

This function plays a metafile into a presentation space.

==Syntax==
 GpiPlayMetaFile(hps, hmf, lCount1, alOptarray, plSegCount, lCount2, pszDesc)

==Parameters==
;hps (HPS) - input:Presentation-space handle.
;hmf (HMF) - input:Metafile handle.
:Handle of the metafile containing the data.
;lCount1 (LONG) - input:Count of elements in alOptarray.
:It must be greater or equal to 0.
;alOptarray (PLONG) - input:Array of options for playing.
:The values of the elements in this array determine what action is to be taken when the metafile is played into the specified presentation space. The elements in the array are numbered consecutively, starting with PMF_SEGBASE. The element number constants start with 0. Any elements in the array that are not set to one of the values defined below must be set to 0.
::alOptarray[PMF_SEGBASE] - Reserved; must be 0. 
::alOptarray[PMF_LOADTYPE] - Specifies what transformations should be performed on the imported picture. The options are:
:::LT_DEFAULT - The default; same as LT_NOMODIFY 
:::LT_NOMODIFY - The graphics are restored using the current viewing transform (see GpiSetViewingTransformMatrix), rather than the ones that were in use when the data was created. ::::This is the default action.
::::Any change to the graphics field or default viewing transform during the course of the picture will be ignored if this option is specified (or defaulted). 
:::;LT_ORIGINALVIEW
::::The graphics are restored using the viewing transforms that are in the metafile.
::::The default viewing transform of the presentation space is not altered (unless RES_RESET is specified). However, any changes to the default viewing transform that occur during the course of the picture (and also any graphics field clipping) cause changes to the values in the presentation space. 
::;alOptarray[PMF_RESOLVE]
:::Reserved; must be 0. 
::;alOptarray[PMF_LCIDS]
:::Specifies the action to be taken for any logical font definitions, or bit maps referenced by local identifiers for use as shading patterns that are held in the metafile.
:::The options are:
:::;LC_DEFAULT
::::Default; same as LC_NOLOAD. 
:::;LC_NOLOAD
::::Do not load such objects. This is the default, and is used where the application expects the correct objects to be already loaded. 
:::;LC_LOADDISC
::::Load all objects referenced in the metafile, first deleting any already existing in the presentation space, for which the referenced local identifier is already in use. 

::;alOptarray[PMF_RESET]
:::Specifies whether the presentation space should be reset before playing the metafile, with the page units and size being set as defined in the metafile.
:::The options are:

:::;RES_DEFAULT
::::Default; same as RES_NORESET. 
:::;RES_NORESET
::::Do not perform a reset. 
:::;RES_RESET
::::Reset the presentation space, before loading any logical fonts, color tables, segments, and so on, as follows:

                        Reset the page units and page size to the values contained in the metafile. 2.
                            Set up default transformations, based on the page units and size, as if the presentation space had just been created with these values. 3.
                            Further modify the device transform to ensure that the physical size of the metafile picture is preserved. (Only performed if the page units in the metafile are not PU_ARBITRARY or PU_PELS.) 4.
                            Perform the equivalent of GpiResetPS (option GRES_ALL). 5.
                            Set the default viewing transform to the value specified in the metafile. This option should normally be used with a PMF_LOADTYPE option of LT_ORIGINALVIEW and LC_LOADDISC, but this is not enforced. 

::;alOptarray[PMF_SUPPRESS]
:::Specifies whether the playing of this metafile actually occurs. This is provided to allow an application to use the PMF_RESET option, and then to regain control to perform further presentation-space modifications if necessary, before playing the remainder of the metafile.
:::The options are:
:::;SUP_DEFAULT
::::Default; same as SUP_NOSUPPRESS. 
:::;SUP_NOSUPPRESS
::::Do not suppress the remainder of the metafile. 
:::;SUP_SUPPRESS
::::Suppress the remainder of the metafile.
::::If this option is selected, only processing as determined by the PMF_RESET option is performed. The remainder of the metafile, and all other options, are ignored. 

::;alOptarray[PMF_COLORTABLES]
:::Specifies the action to be taken with respect to any color table or palette implied or present within the metafile.
:::The options are:
:::;CTAB_DEFAULT
::::Default; same as CTAB_NOMODIFY. 
:::;CTAB_NOMODIFY
::::Ignore. The default or loaded color table or selected palette in the presentation space is unchanged, as are the references to color attributes in the new data. This is the default; it is suitable where it is known that the currently loaded color table or selected palette (if any) is suitable for the use of color in the imported picture. 
:::;CTAB_REPLACE
::::Overwrite the currently-loaded color table (if any), with a color table as implied or present in the metafile. This can be used where there is no existing picture. 
:::;CTAB_REPLACEPALETTE
::::Overwrite the currently-selected palette (if any), with a palette as implied or present in the metafile. This can be used where there is no existing picture.
::::Note: If the metafile specifies a color table in RGB mode, the currently-selected palette (if any) is overwritten with a color table in RGB mode, and a warning is issued. 

::;alOptarray[PMF_COLORREALIZABLE]
:::This index/value is maintained for compatibility with 16-bit programs. It is not applicable to 32-bit programming. 
::;alOptarray[PMF_DEFAULTS]
:::Specifies how the drawing defaults contained in the metafile should be used (see GpiSetDefAttrs, GpiSetDefViewingLimits, GpiSetDefTag, and GpiSetDefArcParams).
:::The options are:
:::;DDEF_DEFAULT
::::Default; same as DDEF_IGNORE 
:::;DDEF_IGNORE
::::Ignore any drawing default values in the metafile. 
:::;DDEF_LOADDISC
::::Change any drawing default values in the presentation space that are specified in the metafile, to the values contained in the metafile. 

;plSegCount (PLONG) - output:Reserved value, must be 0.
;lCount2 (LONG) - input:Count of bytes in pszDesc.
:It must be greater than 0.
;pszDesc (PSZ) - output:Descriptive record.
:pszDesc is a buffer that, on return, contains the descriptive record, of up to 253 bytes, that is saved when the metafile is created (see DevOpenDC in the Presentation Manager Programming Reference.) This is null-terminated, even if it has to be truncated.

==Returns==
;lHits (LONG) - returns:Correlation and error indicators.
::GPI_OK - Successful
::GPI_HITS - Correlate hits
::GPI_ERROR - Error.

==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_HMF (0x207E):An invalid metafile handle was specified. 
;PMERR_INV_LENGTH_OR_COUNT (0x2092):An invalid length or count parameter was specified. 
;PMERR_INV_PLAY_METAFILE_OPTION (0x20B8):An invalid option parameter was specified with GpiPlayMetaFile. 
;PMERR_INCOMPATIBLE_METAFILE (0x203B):An attempt was made to associate a presentation space and a metafile device context with incompatible page units, size or coordinate format; or to play a metafile using the RES_RESET option (to reset the presentation space) to a presentation space that is itself associated with a metafile device context. 
;PMERR_INV_METAFILE (0x209D):An invalid metafile was specified with GpiPlayMetaFile. 
;PMERR_INV_MICROPS_ORDER (0x20A2):An attempt was made to play a metafile containing orders that are invalid in a micro presentation space. 
;PMERR_STOP_DRAW_OCCURRED (0x2105):Segment drawing or GpiPlayMetaFile was stopped prematurely in response to a GpiSetStopDraw request. 
;PMERR_INV_OUTSIDE_DRAW_MODE (0x20AC):An attempt was made to issue a GpiSavePS or GpiRestorePS function, or an output only function (for example, GpiPaintRegion) from GpiPlayMetaFile without the drawing mode set to DM_DRAW. 
;PMERR_INV_ELEMENT_POINTER (0x206B):An attempt was made to issue GpiPutData with the element pointer not pointing at the last element. 
;PMERR_INV_IN_CURRENT_EDIT_MODE (0x2087):An attempt was made to issue a function invalid inside the current editing mode. 
;PMERR_PROLOG_ERROR (0x20F2):A prolog error was detected during drawing. Segment prologs are used internally within retained segments and also appear in metafiles. This error can also arise from an End Prolog order that is outside a prolog.
;PMERR_DUP_SEG (0x2027):During GpiPlayMetaFile, while the actual drawing mode was draw-and-retain or retain, a metafile segment to be stored in the presentation space was found to have the same segment identifier as an existing segment.

==Remarks==
This function executes the contents of a metafile. This process is known as "playing" the metafile. Whether the graphics are drawn, or retained in segment store, or both, depends upon the current drawing mode (see GpiSetDrawingMode) in the presentation space, for the chained and unchained segment contexts, as appropriate. If chained segments are retained, they are added to the end of any existing segment chain. An error is raised if a segment is to be retained, and it has the same (nonzero) identifier as a currently existing segment.

A segment must not be open when this function is issued. At the completion of the call, there is no open segment.

The application may need to reset the presentation space by GpiResetPS, before issuing this function. Alternatively, the PMF_RESET option on this function may be suitable.

Segments retain the segment attributes that they originally possessed.

==Example Code==
This example uses the GpiPlayMetaFile function to play (execute) the metafile loaded by GpiLoadMetaFile into a presentation space associated with a window. GpiPlayMetaFile is called twice: the first call resets the presentation space (by combining the RES_RESET and SUP_SUPPRESS flags), while the second call actually executes the metafile.
<pre>
#define INCL_GPIMETAFILES       /* Metafile functions           */
#define INCL_GPICONTROL         /* GPI control Functions        */
#include <os2.h>

HAB    hab;             /* anchor-block handle                  */
HPS    hps;             /* presentation space handle            */
HMF    hmf;             /* metafile handle                      */
HDC    hdc;             /* Device-context handle                */
HWND   hwnd;            /* window handle                        */
SIZEL  sizl={0,0};      /* use same page size as device         */
CHAR   szBuffer[80];    /* descriptive record buffer            */
LONG     lHits;         /* correlation/error indicator          */
/* play metafile options array */
LONG optArray[PMF_DEFAULTS+1] =
                          {0,LT_DEFAULT,0,LC_DEFAULT,RES_RESET,
                          SUP_SUPPRESS,CTAB_DEFAULT,CREA_DEFAULT,
                          DDEF_DEFAULT};

hmf = GpiLoadMetaFile(hab, "sample.met");

/* create window device context and presentation space,
   associating DC with the PS */
hdc = WinOpenWindowDC(hwnd);
hps = GpiCreatePS(hab, hdc, &sizl, PU_PELS | GPIA_ASSOC);

/* reset presentation space */
lHits = GpiPlayMetaFile(hps, hmf, 9L, optArray, (LONG *)0, 80L,
                        szBuffer);

/* display metafile in window (reset and
   suppress flags must be changed) */
optArray[PMF_SUPPRESS]=SUP_DEFAULT;
optArray[PMF_RESET]=RES_DEFAULT;
lHits = GpiPlayMetaFile(hps, hmf, 9L, optArray, (LONG *)0, 80L,
                        szBuffer);
</pre>

==Related Functions==
* GpiCopyMetaFile
* GpiDeleteMetaFile
* GpiLoadMetaFile
* GpiQueryMetaFileBits
* GpiQueryMetaFileLength
* GpiSaveMetaFile
* GpiSetMetaFileBits

[[Category:Gpi]]