PhDCCreate()

Create and initialize a new draw context

Synopsis:

PhDrawContext_t *PhDCCreate( 
                   int type,
                   long flags,
                   int (*flush)(int Subtype),
                   int (*modify)(PhDrawContext_t *dc,
                                 int acquire,
                                 void *data ) );

Arguments:

type

The type of draw context:

• Ph_DRAW_TO_MEMORY_CONTEXT — the context being created will draw to memory.
• Ph_DRAW_TO_OFFSCREEN_MEMORY — emit the draw stream to offscreen memory.
• Ph_DRAW_TO_PHOTON — normal draw mode.
• Ph_DRAW_TO_PRINT_CONTEXT — create a context that's compatible with the Pp* api and will embed the required printer control codes in the draw stream and allow you to direct the draw stream to an external source (spooler/file)
• Ph_DRAW_TO_SERVICE — emit the draw stream directly to a service provider.

flags

Flags that apply to the context:

• Ph_INLINE_SHMEM_OBJECTS — shared objects are inlined in the draw stream. This ensures the interpreter of the draw stream can access the data. It's possible that the interpreter is on a different machine and doesn't have access to the shared objects refered to or may be interpreting the draw stream weeks later, when the shared objects no longer exist.
• Ph_TEXT_EXTENTS — include bounding rectangles for drawn text. This extra information can be used by remote viewers (Phindows etc.) to find a font that matches the desired size as possible. Used internally.
• Ph_SUPRESS_PARENT_CLIP — when a widget draw cycle begins, the parents of the starting widget are traversed and their canvases are intersected to determine the clipping to be used during the draw. If this flag is set, that step is skipped. As a result, all of the starting widget is visible in the draw stream (as if it isn't clipped). This is important (for example) for printing large widgets in small containers.
• Ph_SYNC_GCS — force a “sync GC” command to be placed at the beginnig of each draw stream. This command causes the graphics driver to wait for a vertical retrace before processing the draw commands.

flush

The function to be called whenever the current draw buffer needs to be flushed. If not provided, the standard Photon graphic flush function is used.

The Subtype argument is what's passed by PgFFlush().

modify

A function that's called whenever this draw control is to be modified. The modification is restricted by the type of the draw control (e.g. if the type is Ph_DRAW_TO_PRINTER, you can target a different printer but can't target memory with subsequent calls to the modify function).

The arguments are:

• dc — a pointer to the draw context structure.
• action — what's being done to the draw context; one of:
  • Ph_CREATED_DC
  • Ph_ACTIVATE_DC
  • Ph_DEACTIVATE_DC
  • Ph_DESTROYING_DC
• data — a pointer to arbitrary data you want to pass to the function.

Library:

ph

Description:

This function creates a draw context structure and initializes its flush and attach functions. The type argument is recorded in the new draw control and prevents the DC from being used as anything but its current type.

---

You aren't likely to call this function directly unless you're creating your own type of draw context. The functions that create specific types of contexts (e.g. direct-mode, printer, and memory) call PhDCCreate().

---

Returns:

A pointer to the newly allocated draw context, or NULL if there isn't enough memory.

Classification:

Photon

See also:

PdCreateDirectContext(), PdCreateOffscreenContext(), PhDCSetCurrent(), PhDCGetCurrent(), PhDCRelease(), PmMemCreateMC(), PpCreatePC()