3.1.3 How do I use a CXR?

To use a CXR, two things are required. First, you explicitly tell Cogsys to load the extension. Second, you use a command which (implicitly or explicitly) makes uses of the loaded extension.

Currently, in Cogsys 3.0.15, only one extension may be loaded at a time. The Load External Routine command (code %X) is used to load an extension. It automatically unloads any previously loaded extension. Its syntax and use are described in detail in Extensions. To summarize that description here, it is a very simple command: it takes a single argument which is the name of CXR file. For example:

%X[randext.cxr]

Now that the extension is loaded, it is available to any CXR-aware command. In Cogsys 3.0.15, only one such command exists, Create Pictures from CXR (code %I). Create Pictures from CXR implicitly uses the single loaded extension routine to draw pictures into memory which can then be used with any of the picture display commands.

The details of Create Pictures from CXR are described in Command Reference. To summarize, Create Pictures is first told the number of pictures it is to generate. Then, it is optionally given a preimage argument, specified with Pimagenumber. The preimage argument specifies the index of an existing picture that is used as the background before Create Pictures draws a picture. If not specified, a blank black background is usually used, but that depends on the extension: an extension can choose not to erase the background first to create superimposition effect (see section Passed Arguments). Finally, the third argument to Create Pictures is actually a comma-separated list of strings, integer, and floating point constants. Create Pictures sends this list of constants to the CXR. The CXR then makes use of the list any way it likes to actually create the pictures. This means the syntax of the arguments in %I totally depends on which extension is being used.

For example, here the `RANDEXT.CXR' file is loaded as above. Then, Create Pictures is called to geneated one picture, a solid green frame, using RANDEXT. Finally, the picture is displayed, switching into Cogsys Mode 2 first. (Currently, all picture generating extensions create Type 2 pictures, which require mode 2; but there is nothing in the extension mechanism that require this to be the case.) The complete list looks like this:

%X[randext.cxr] %I[1,2,10] %M2 #B[1,20]

Above, the first `1' in the arguments to %I means one picture is requested. No preimage is specified (if it was, the second argument would be of the form Pimagenumber. The next two arguments, `1,10', are specific to the RANDEXT extension. As documented in the user reference pages for the RANDEXT command (see section RANDEXT), the first argument to this extension is a subfunction selector. Subfunction number 2 is a solid color field. When using subfunction 2, the next argument is the color. In the standard Cogsys Mode 2 palette (see section Standard Palette), 10 is green. The above testlist will display a 320x200 pixel field of green centered on the screen.

For more details on using the included Cogsys extensions, see Extension Reference.