RFC PS Rasterizer Library API

We've got the basic functionality of using my postscript interpreter, xpost, as a library. I'd like to solicit some feedback from the community on the API setup. This example program, called xpost_client.c illustrates the API to rasterize a small EPS into a 792x612 BGR buffer, which it then dumps to a file as an ASCII PPM file (so you can check it with a text editor).

/* 
   This is a simple example of a client calling xpost as a library 
   with a postscript program, desiring the raster data of the 
   generated image. 

TODO: 
    define buffer interchange type 
 */ 

#include  
#include  

#include "xpost.h" 
#include "xpost_memory.h" 
#include "xpost_object.h" 
#include "xpost_context.h" 
#include "xpost_interpreter.h" 

char *prog = 
    "%%BoundingBox: 200 300 400 500\n" 
    "300 400 100 0 360 arc\n" 
    "fill\n" 
    "showpage\n"; 

int main() { 
    void *buffer_type_object; 
    xpost_init(); 
    xpost_create("bgr", 
            XPOST_OUTPUT_BUFFEROUT, 
            &buffer_type_object, 
            XPOST_SHOWPAGE_RETURN, 
            1); 
    xpost_run(XPOST_INPUT_STRING, prog); 
    { 
        unsigned char *buffer = buffer_type_object; 
        int i,j; 
        FILE *fp = fopen("xpost_client_out.ppm", "w"); 
        fprintf(fp, "P3\n612 792\n255\n"); 
        for (i=0; i<792; i++) { 
            for (j=0; j<612; j++) { 
                unsigned int red, green, blue; 
                red = *buffer++; 
                green = *buffer++; 
                blue = *buffer++; 
                ++buffer; 
                fprintf(fp, "%d ", red); 
                fprintf(fp, "%d ", green); 
                fprintf(fp, "%d ", blue); 
                if ((j%20)==0) 
                    fprintf(fp, "\n"); 
            } 
            fprintf(fp, "\n"); 
        } 
        fclose(fp); 
    } 
    xpost_destroy(); 
    free(buffer_type_object); 
    xpost_quit(); 
    return 0;
}

Currently only the bgr device offers the OUTPUT_BUFFEROUT option. The C

Based on these two lines…

xpost_create("bgr", 
        XPOST_OUTPUT_BUFFEROUT, 
        &buffer_type_object, 
        XPOST_SHOWPAGE_RETURN, 
        1); 
xpost_run(XPOST_INPUT_STRING, prog);

I am puzzled by the interaction between xpost_create() and xpost_run(). Is it possible to create and use multiple xpost contexts at once? If so, shouldn't xpost_create() return some kind of handle that would be passed as a parameter to xpost_run()? Or, if not, then why should I need to call xpost_create() and xpost_destroy() at all?

I would expect the library to behave more like a printer, in that it would produce an image for every showpage command. One way to make that work would be to register a callback, which would be called whenever showpage is encountered. Perhaps it could pass some information about the bounding box as parameters to the callback, since it's unreasonable to have to guess or hard-code that information.

It's odd that the color model is called "bgr", but the pixel values are arranged in the opposite order (red, green, blue) in the output buffer. I would also consider treating the buffer as an array of

typedef {
    int red;
    int green;
    int blue;
} struct pixel;

… instead of separate red, green, and blue integers.

Your example client doesn't seem to demonstrate any error-handling capability. What happens, for example, if the PostScript interpreter has a stack underflow?

StackExchange Code Review Q#65061, answer score: 3