PhDCSetCurrent()

Set the currently active draw context

Synopsis:

PhDrawContext_t *PhDCSetCurrent( 
                     void *draw_context );

Arguments:

draw_context: A pointer to the draw context to be made the default one.

Description:

This function makes the provided draw_context active. Calling this function with NULL makes the default draw context active. The default draw context emits draws to graphics drivers via Photon.

A draw context is anything that defines the flow of the draw stream. Print contexts and memory contexts are types of draw contexts — it may help to think of them as specialized subclasses of the draw context.

Contexts that may be set using this function:

Draw contexts: There's usually only one basic draw context per application. Draw contexts are used to deliver the draw stream to graphics drivers via Photon.
Print contexts: Created via PpCreatePC(). Print contexts are used to produce printed output from Photon applications.
Memory contexts: Created via PmMemCreateMC(). Memory contexts are used to draw into memory to build images for manipulation or display.

Returns:

The old draw context, or NULL if the new context can't be made current (active), in which case errno has specifics of the error.

Examples:

In the following example, the print context pc is made active by calling PpContinueJob(). PpContinueJob() returns the context that the print context is replacing. The returned context is stored to enable us to restore the context that was active at the time we decided to start printing.

PhDrawContext_t *dc;
PpPrintContext_t *pc;
PmMemoryContext_t *mc;
...
if( ( dc = PpContinueJob( pc ) ) == -1 )
    {
        perror( "unable to activate print context" );
    }
    else{
        // do print stuff

        // Then restore context which was active before we
        // started printing.  This is equivalent to doing
        // a PpSuspendJob() followed by a PmMemStart(), or
        // PpContinueJob(), depending on what type of draw
        // context was active previously.

        PhDCSetCurrent( dc );
    }

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No