Load or alter precompiled commands in a blit

Name

ggiBltPutBatchop, ggiBltPutBlit, ggiBltPutReverseBlit, ggiBltPutStretchBlit, ggiBltPutZBlit, ggiBltPutABlit, ggiBltAlterBobIdx, ggiBltAlterCoord, ggiBltAlterBox, ggiBltAlterStretchBox, ggiBltAlterZ, ggiBltAlterA : Load or alter precompiled commands in a blit

Synopsis

#include <ggi/blt.h>

int ggiBltPutBatchop(ggiBlt_t into, batchop_t from, int numrows);

int ggiBltPutBlit(ggiBlt_t blt, ggiBlt_source_t source,
                  long x, long y, int w, int h);

int ggiBltPutReverseBlit(ggiBlt_t blt, ggiBlt_source_t dest,
                         long x, long y, int w, int h);

int ggiBltPutStretchBlit(ggiBlt_t blt, ggiBlt_source_t source,
                         long x, long y, int sw, int sh, long dw, long dh);

int ggiBltPutZBlit(ggiBlt_t blt, ggiBlt_source_t source,
                   long x, long y, int w, int h,
                   int ztl, int zbr);

int ggiBltPutABlit(ggiBlt_t blt, ggiBlt_source_t source,
                   long x, long y, int w, int h,
                   int atl, int abr);

int ggiBltAlterBobIdx(ggiBlt_t blt, int *bobidx, int numrows);

int ggiBltAlterCoord(ggiBlt_t blt, long *x, long *y, int numrows);

int ggiBltAlterBox(ggiBlt_t blt, long *x, long *y, int *w, int *h, 
                   int numrows);

int ggiBltAlterStretchBox(ggiBlt_t blt, long *x, long *y, int *w, int *h, 
                          int numrows);

int ggiBltAlterZ(ggiBlt_t blt, int *ztl, int *zbr, int numrows);

int ggiBltAlterA(ggiBlt_t blt, int *atl, int *abr, int numrows);

Description

ggiBltPutBatchop loads values from a libmmutils batchop structure into a blit. It is for advanced users, and the exact standards for user-defined batchops have not been specified yet.

The rest of the ggiBltPut* functions share some common parameters and behaviors: all the commands load a request for a single blitting operation into the blit designated by the parameter blt. The operation is loaded at the row index of the blit, as set by ggiBltSetIdx, and after the operation is added, the row index is incremented automatically. Properties such as the texture index, color key values, and raster operation are copied from the BOB (or other type of LibBlt source) designated by the parameter source. Use of the word "copied" in the last sentence is important, as subsequently changing these values in the BOB will not change the values stored in the precompiled command.

Except where otherwise noted, the parameters x and y refer to a coordinate on the main visual represented (as standard in GGI extensions) as an offset from the top left corner of the visual to which the blit belongs, designating the top left corner of the affected area on the visual, and are in the coordinate base units last set with ggiBltSetCoordbase. Contrarily, parameters w and h represent the dimensions of the rendered object in the units of the pixels or values as stored in the BOB's managed area, and will correspond to pixels on the main visual.

The function ggiBltPutBlit fills the row with a command that performs a standard, no-frills blit operation, and the function ggiPutReverseBlit fills the row with a command that will take data from the framebuffer rather than pushing data to the framebuffer.

ggiBltPutStretchBlit fills the row with a command that performs an interpolated stretching or shrinking operation. The parameters sw and sh work the same as the parameters w and h do in the other functions, but do not affect the size of the rendered area on the visual. The parameters dw and dh designate the size of the rendered area on the visual, and are in the coordinate base last set with ggiBltSetCoordbase.

The function ggiBltPutZBlit fills the row with a command that will perform Z-clipping on a visual which has been clad via the LibBuf function ggiBufCladVis(3). The source Z depth is interpolated linearly along both axis between the value ztl, which represents the Z depth at the top left corner of the affected area, and zbr, which represents the Z depth at the bottom right corner of the affected area.

The function ggiBltPutABlit fills the row with a command that will perform A blending on a visual which has been clad via the LibBuf function ggiBufCladVis(3). The source alpha blend factor is interpolated linearly along both axis between the value atl, which represents the alpha at the top left corner of the affected area, and abr, which represents the alpha blend factor at the bottom right corner of the affected area.

The ggiBltAlter* allow the coordinates, sizes, texture indexes, Z-depths, and alpha blend factors placed into a precompiled commands in the blit designated by blt to be altered en-mass in a number of consecutive rows (designated by the parameter numrows). If the values being altered are not pertinant to a given row (e.g. ggiBltAlterA is attempts to alter a row which does not contain a command that performs alpha blending) they are silently ignored for that row.

ggiBltAlterBobIdx alters the texture indexes which were imparted to the precompiled command contained in each specified row by the BOB or other LibBlt source which was originally used to create the command, changing the indexes to the values stored in the array designated by the parameter bobidx.

ggiBltAlterCoord alters the x,y coordinates of the top left corner of the affected area on the visual. x coordinates are loaded from the array designated by the parameter x, and y coordinates are loaded from the array designated by the parameter y. The values loaded are interperated as described above, which means that they use coordinate base units as set via the most recent call to ggiBltSetCoordBase, not the coordinate base units which were in effect when the precompiled command was originally added to the row.

ggiBltAlterBox functions the same as ggiBltAlterCoord, with the additional parameters w and h, which designate arrays from which to load new values for the width and height of the texture to be copied, as described above.

ggiBltAlterStretchBox functions the same as ggiBltAlterBox, except that the parameters sw and sh take the place of x and y, and with the additional parameters dw and dh, which designate arrays from which to load new values for the width and height of the affected area on the visual, using the coordinate base units as set via the most recent call to ggiBltSetCoordBase, not the coordinate base units which were in effect when the precompiled command was originally added to the row.

The function ggiBltAlterA alters top left and bottom right source Z depths originally created by ggiBltPutZBlit, using the values stored in the arrays designated by the parameters atl and abr, respectively.

The function ggiBltAlterA alters top left and bottom right source alpha values originally created by ggiBltPutABlit, using the values stored in the arrays designated by the parameters ztl and zbr, respectively.

Return value

All functions return 0 (GGI_OK) for OK or a negative value on failure.

Examples

Make a bunch of objects dance around the screen:

ggiBltSetIdx(blt, 0);

for (i = 0; i < numobjects; i++) {
      ggiBltPutBlit(blt, bob, 0, 0, 25, 25);
      ggiBltSetSourceIdx(source, i);
}
x = malloc(sizeof(long) * numobjects);
y = malloc(sizeof(long) * numobjects);
i = 0;
while (i++ < 3000) {
      GetNewCoordinates(i, x, y);
      ggiBltAlterCoord(blt, x, y, numobjects);
      ggiBltGo(blt, 0, numbjects);
      ggiFlush();
      usleep(100);
}