PgmViewport

## PgmViewport PgmViewport — An abstract class doing a visual projection of a canvas. |

## Synopsis

    #include <pgm/pgm.h>

    enum                PgmViewportCursor;
    enum                PgmViewportCapacity;
    enum                PgmViewportRotation;
    enum                PgmViewportReflection;
                        PgmViewport;
                        PgmViewportClass;
    PgmError            pgm_viewport_set_title              (PgmViewport *viewport,
                                                             const gchar *title);
    PgmError            pgm_viewport_get_title              (PgmViewport *viewport,
                                                             gchar **title);
    PgmError            pgm_viewport_show                   (PgmViewport *viewport);
    PgmError            pgm_viewport_hide                   (PgmViewport *viewport);
    PgmError            pgm_viewport_is_visible             (PgmViewport *viewport,
                                                             gboolean *visible);
    PgmError            pgm_viewport_set_decorated          (PgmViewport *viewport,
                                                             gboolean decorated);
    PgmError            pgm_viewport_get_decorated          (PgmViewport *viewport,
                                                             gboolean *decorated);
    PgmError            pgm_viewport_set_cursor             (PgmViewport *viewport,
                                                             PgmViewportCursor cursor);
    PgmError            pgm_viewport_get_cursor             (PgmViewport *viewport,
                                                             PgmViewportCursor *cursor);
    PgmError            pgm_viewport_set_icon               (PgmViewport *viewport,
                                                             GdkPixbuf *icon);
    PgmError            pgm_viewport_get_icon               (PgmViewport *viewport,
                                                             GdkPixbuf **icon);
    PgmError            pgm_viewport_set_size               (PgmViewport *viewport,
                                                             gint width,
                                                             gint height);
    PgmError            pgm_viewport_get_size               (PgmViewport *viewport,
                                                             gint *width,
                                                             gint *height);
    PgmError            pgm_viewport_set_alpha_blending     (PgmViewport *viewport,
                                                             gboolean alpha_blending);
    PgmError            pgm_viewport_get_alpha_blending     (PgmViewport *viewport,
                                                             gboolean *alpha_blending);
    PgmError            pgm_viewport_set_opacity            (PgmViewport *viewport,
                                                             guchar opacity);
    PgmError            pgm_viewport_get_opacity            (PgmViewport *viewport,
                                                             guchar *opacity);
    PgmError            pgm_viewport_set_fullscreen         (PgmViewport *viewport,
                                                             gboolean fullscreen);
    PgmError            pgm_viewport_get_fullscreen         (PgmViewport *viewport,
                                                             gboolean *fullscreen);
    PgmError            pgm_viewport_set_iconified          (PgmViewport *viewport,
                                                             gboolean iconified);
    PgmError            pgm_viewport_get_iconified          (PgmViewport *viewport,
                                                             gboolean *iconified);
    PgmError            pgm_viewport_focus                  (PgmViewport *viewport);
    PgmError            pgm_viewport_get_screen_resolution  (PgmViewport *viewport,
                                                             gint *width,
                                                             gint *height);
    PgmError            pgm_viewport_set_screen_resolution  (PgmViewport *viewport,
                                                             gint width,
                                                             gint height);
    PgmError            pgm_viewport_get_screen_size_mm     (PgmViewport *viewport,
                                                             gint *width,
                                                             gint *height);
    PgmError            pgm_viewport_set_screen_size_mm     (PgmViewport *viewport,
                                                             gint width,
                                                             gint height);
    PgmError            pgm_viewport_set_message_filter     (PgmViewport *viewport,
                                                             GList *filter);
    PgmError            pgm_viewport_get_message_filter     (PgmViewport *viewport,
                                                             GList **filter);
    PgmError            pgm_viewport_push_event             (PgmViewport *viewport,
                                                             PgmEvent *event);
    PgmError            pgm_viewport_get_canvas             (PgmViewport *viewport,
                                                             PgmCanvas **canvas);
    PgmError            pgm_viewport_set_canvas             (PgmViewport *viewport,
                                                             PgmCanvas *canvas);
    PgmError            pgm_viewport_set_canvas_rotation    (PgmViewport *viewport,
                                                             PgmViewportRotation rotation);
    PgmError            pgm_viewport_get_canvas_rotation    (PgmViewport *viewport,
                                                             PgmViewportRotation *rotation);
    PgmError            pgm_viewport_set_canvas_reflection  (PgmViewport *viewport,
                                                             PgmViewportReflection reflection);
    PgmError            pgm_viewport_get_canvas_reflection  (PgmViewport *viewport,
                                                             PgmViewportReflection *reflection);
    PgmError            pgm_viewport_update_projection      (PgmViewport *viewport);
    PgmError            pgm_viewport_to_canvas              (PgmViewport *viewport,
                                                             gfloat *canvas_x,
                                                             gfloat *canvas_y,
                                                             gfloat *canvas_z,
                                                             gfloat viewport_x,
                                                             gfloat viewport_y,
                                                             gfloat viewport_z);
    PgmError            pgm_viewport_from_canvas            (PgmViewport *viewport,
                                                             gfloat *viewport_x,
                                                             gfloat *viewport_y,
                                                             gfloat *viewport_z,
                                                             gfloat canvas_x,
                                                             gfloat canvas_y,
                                                             gfloat canvas_z);
    PgmError            pgm_viewport_get_embedding_id       (PgmViewport *viewport,
                                                             gulong *embedding_id);
    PgmError            pgm_viewport_get_pixel_formats      (PgmViewport *viewport,
                                                             gulong *formats_mask);
    PgmError            pgm_viewport_get_caps_mask          (PgmViewport *viewport,
                                                             gulong *caps_mask);
    PgmError            pgm_viewport_get_max_texture_size   (PgmViewport *viewport,
                                                             guint32 *max_texture_size);
    PgmError            pgm_viewport_get_frame_rate         (PgmViewport *viewport,
                                                             guint *frame_rate);
    PgmError            pgm_viewport_read_pixels            (PgmViewport *viewport,
                                                             guint x,
                                                             guint y,
                                                             guint width,
                                                             guint height,
                                                             guint8 *pixels);
    PgmError            pgm_viewport_push_pixels            (PgmViewport *viewport,
                                                             guint width,
                                                             guint height,
                                                             guint8 *pixels);
    PgmError            pgm_viewport_emit_update_pass       (PgmViewport *viewport);

## Object Hierarchy

      GObject
       +----GstObject
             +----PgmViewport

## Signals

      "button-press-event"                             : Run Last
      "button-pressure-event"                          : Run Last
      "button-release-event"                           : Run Last
      "configure-event"                                : Run Last
      "delete-event"                                   : Run Last
      "drag-drop-event"                                : Run Last
      "drag-leave-event"                               : Run Last
      "drag-motion-event"                              : Run Last
      "expose-event"                                   : Run Last
      "key-press-event"                                : Run Last
      "key-release-event"                              : Run Last
      "motion-notify-event"                            : Run Last
      "pixels-read"                                    : Run Last
      "scroll-event"                                   : Run Last
      "state-event"                                    : Run Last
      "update-pass"                                    : Run Last

## Description

### Implementation capacities

A PgmViewport object is used to do a visual projection of PgmCanvas object. Each PgmDrawable added to the canvas is rendered on the viewport converting canvas coordinates to display coordinates. Viewport is a base abstract class from which implementation plugins inherit. You can instantiate several viewport implementations through a PgmViewportFactory. A viewport can handle 0 or 1 canvas, if there's no canvas binded, nothing is projected except the background color of the viewport.

Each viewport implementations are based on a dedicated graphical library such as DirectFB, OpenGL or Direct3D to project the binded canvas. These libraries can be completely different, some of them being 2d-based generating their output through blit operations, other being 3d-based generating their output through a 3d pipeline. Each of them can also optimize part of their rendering paths thanks to dedicated hardware. These differences can lead to viewport implementations with different capacities. The result being that some properties of a drawable could not be correctly projected by some implementations. You can retrieve the mask capacities handled by a Viewport at runtime with the `pgm_viewport_get_caps_mask()` method, and you can get the list of handled color spaces with `pgm_viewport_get_pixel_formats()`.

A viewport is responsible of the event handling. It catches the events generated by the underlying backend, and converts them building Pigment events, which are then dispatched through signals. You can connect functions to these signals using `g_signal_connect()` , in UI programming these functions are often called callbacks. Each time an event is generated, the corresponding signal is emited and all the connected callbacks are called.

Practically speaking, the viewport is basically either a window on your screen or your complete monitor/TV. When you define the size of the viewport, the implementation will try to change the window size, or the video mode if you set it to be fullscreen. Some viewport implementation are not able to obtain the screen size in millimeters and you have to set it, so that the viewport can calculate the appropriate projections taking in account non square pixels.

Applications are strongly encouraged to use the viewport the following way:

- The application initializes Pigment using pgm_init and then try to get the screen size in millimeters, the screen resolution and the viewport size (window size or fullscreen size). Looking at those parameters the application can calculate the pixel aspect ratio of the screen and figure out the visual aspect ratio of the viewport (4:3, 16:9, etc).

- When the application has defined the visual aspect ratio of the viewport, it can decide the visual aspect ratio it's going to generate and set the canvas size accordingly. Let's say for example that the viewport size is a 750x400 pixels window and that we have square pixels, this is a bit wider than 16:9. The application decides to generate a 16:9 style user interface and sets the canvas to 16.0x9.0. The viewport will draw black borders and project that canvas as a 711x400 pixels large rectangle in the middle of that window.

- If the viewport size changes (window resize), the application can decide to use another aspect ratio or stick with the current one.

Last reviewed on 2007-06-10 (0.1.5)

## Details

### enum PgmViewportCursor

    typedef enum {
      PGM_VIEWPORT_LEFT_ARROW = 0,
      PGM_VIEWPORT_INHERIT    = 1,
      PGM_VIEWPORT_NONE       = 2
    } PgmViewportCursor;

Pigment system cursor type.

`PGM_VIEWPORT_LEFT_ARROW` | Standard left arrow system cursor.
`PGM_VIEWPORT_INHERIT` | Inherited cursor from the environment.
`PGM_VIEWPORT_NONE` | Hidden cursor.

### enum PgmViewportCapacity

    typedef enum {
      PGM_VIEWPORT_HARDWARE_ACCELERATION = (1 << 0),
      PGM_VIEWPORT_APPLICATION_EMBEDDING = (1 << 1),
      PGM_VIEWPORT_OPACITY               = (1 << 2),
      PGM_VIEWPORT_TOUCHPAD              = (1 << 3),
      PGM_VIEWPORT_X11_SYSTEM_BUFFER     = (1 << 4)
    } PgmViewportCapacity;

Capacities supported by the viewport.

`PGM_VIEWPORT_HARDWARE_ACCELERATION` | Supports accelerated rendering thanks to dedicated hardware.
`PGM_VIEWPORT_APPLICATION_EMBEDDING` | Supports embedding into another application.
`PGM_VIEWPORT_OPACITY` | Supports opacity so that compositing managers can blend the viewport with other applications.
`PGM_VIEWPORT_TOUCHPAD` | Supports touchpad so that application can use the pressure events and parameters.
`PGM_VIEWPORT_X11_SYSTEM_BUFFER` | Supports X11 system buffer as image content. Actually, X11 system buffers are Pixmaps.

### enum PgmViewportRotation

    typedef enum {
      PGM_VIEWPORT_ROTATION_NONE = 0,
      PGM_VIEWPORT_ROTATION_90   = 1,
      PGM_VIEWPORT_ROTATION_180  = 2,
      PGM_VIEWPORT_ROTATION_270  = 3
    } PgmViewportRotation;

The rotation types of the canvas projection.

`PGM_VIEWPORT_ROTATION_NONE` | Do not rotate to the canvas.
`PGM_VIEWPORT_ROTATION_90` | Rotate the canvas 90° counter-clockwise.
`PGM_VIEWPORT_ROTATION_180` | Rotate the canvas 180° counter-clockwise.
`PGM_VIEWPORT_ROTATION_270` | Rotate the canvas 270° counter-clockwise.

### enum PgmViewportReflection

    typedef enum {
      PGM_VIEWPORT_REFLECTION_NONE            = 0,
      PGM_VIEWPORT_REFLECTION_HORIZONTAL_FLIP = 1,
      PGM_VIEWPORT_REFLECTION_VERTICAL_FLIP   = 2
    } PgmViewportReflection;

The reflection types of the canvas projection.

`PGM_VIEWPORT_REFLECTION_NONE` | Do not reflect to the canvas.
`PGM_VIEWPORT_REFLECTION_HORIZONTAL_FLIP` | Reflect the canvas horizontally.
`PGM_VIEWPORT_REFLECTION_VERTICAL_FLIP` | Reflect the canvas vertically.

### PgmViewport

    typedef struct {
      PgmViewportFactory *factory;
      PgmCanvas          *canvas;

      GList *message_filter;

      gchar             *title;
      GdkPixbuf         *icon;
      PgmViewportCursor  cursor;
      gboolean           fullscreen;
      gboolean           visible;
      gboolean           decorated;
      gboolean           iconified;
      gboolean           alpha_blending;

      gint width, height;
      gint width_mm, height_mm;

      PgmMat4x4 *projection, *inv_projection;
      gint       projected_x, projected_y;
      gint       projected_width, projected_height;

      PgmViewportRotation   rotation;
      PgmViewportReflection reflection;

      gfloat pixel_aspect_ratio;
      gfloat viewport_ratio;
      gfloat canvas_ratio;

      gulong caps_mask;

      guchar opacity;
    } PgmViewport;

The PgmViewport structure.

PgmViewportFactory *`factory`; | the factory used to instantiate the PgmViewport.
PgmCanvas *`canvas`; | the attached canvas.
GList *`message_filter`; | the filter of message events.
gchar *`title`; | the viewport title.
GdkPixbuf *`icon`; | the current icon.
PgmViewportCursor `cursor`; | the current cursor.
gboolean `fullscreen`; | the fullscreen state.
gboolean `visible`; | the visible state.
gboolean `decorated`; | the decorated state.
gboolean `iconified`; | the iconified state.
gboolean `alpha_blending`; | the alpha blending state.
gint `width`; | the viewport width.
gint `height`; | the viewport height.
gint `width_mm`; | the viewport screen width in millimeters.
gint `height_mm`; | the viewport screen height in millimeters.
PgmMat4x4 *`projection`; | the 4x4 projection matrix.
PgmMat4x4 *`inv_projection`; | the 4x4 inverse projection matrix.
gint `projected_x`; | the attached canvas projected x position.
gint `projected_y`; | the attached canvas projected y position.
gint `projected_width`; | the attached canvas projected width.
gint `projected_height`; | the attached canvas projected height.
PgmViewportRotation `rotation`; | the rotation of the projected canvas.
PgmViewportReflection `reflection`; | the reflection of the projected canvas.
gfloat `pixel_aspect_ratio`; | the pixel-aspect-ratio.
gfloat `viewport_ratio`; | the viewport ratio.
gfloat `canvas_ratio`; | the attached canvas ratio with pixel-aspect-ratio correction applied.
gulong `caps_mask`; | the viewport mask of supported capacities.
guchar `opacity`; | the opacity.

### PgmViewportClass

    typedef struct {
      GstObjectClass parent_class;

      /* signals */

      void     (*button_press_event)    (PgmViewport *viewport,
                                         PgmEventButton *event);

      void     (*button_pressure_event) (PgmViewport *viewport,
                                         PgmEventButton *event);

      void     (*button_release_event)  (PgmViewport *viewport,
                                         PgmEventButton *event);

      void     (*key_press_event)       (PgmViewport *viewport,
                                         PgmEventKey *event);

      void     (*key_release_event)     (PgmViewport *viewport,
                                         PgmEventKey *event);

      void     (*configure_event)       (PgmViewport *viewport,
                                         PgmEventConfigure *event);

      void     (*delete_event)          (PgmViewport *viewport,
                                         PgmEvent *event);

      void     (*scroll_event)          (PgmViewport *viewport,
                                         PgmEventScroll *event);

      void     (*motion_notify_event)   (PgmViewport *viewport,
                                         PgmEventMotion *event);

      void     (*expose_event)          (PgmViewport *viewport,
                                         PgmEventExpose *event);

      gboolean (*drag_motion_event)     (PgmViewport *viewport,
                                         PgmEventDnd *event);

      void     (*drag_drop_event)       (PgmViewport *viewport,
                                         PgmEventDnd *event);

      void     (*drag_leave_event)      (PgmViewport *viewport,
                                         PgmEventDnd *event);

      void     (*state_event)           (PgmViewport *viewport,
                                         PgmEventState *event);

    #ifdef WIN32
      LRESULT  (*win32_message_event)   (PgmViewport *viewport,
                                         PgmEventWin32Message *event);
    #endif /* WIN32 */

      void     (*pixels_read)           (PgmViewport *viewport,
                                         guint width,
                                         guint height,
                                         gpointer pixels);

      void     (*update_pass)           (PgmViewport *viewport);

      /* virtual methods for subclasses */

      PgmError (*set_title)             (PgmViewport *viewport,
                                         const gchar *title);

      PgmError (*show)                  (PgmViewport *viewport);
      PgmError (*hide)                  (PgmViewport *viewport);

      PgmError (*set_decorated)         (PgmViewport *viewport,
                                         gboolean decorated);

      PgmError (*set_cursor)            (PgmViewport *viewport,
                                         PgmViewportCursor cursor);

      PgmError (*set_icon)              (PgmViewport *viewport,
                                         GdkPixbuf *icon);

      PgmError (*set_size)              (PgmViewport *viewport,
                                         gint width,
                                         gint height);
      PgmError (*get_size)              (PgmViewport *viewport,
                                         gint *width,
                                         gint *height);

      PgmError (*set_alpha_blending)    (PgmViewport *viewport,
                                         gboolean alpha_blending);

      PgmError (*set_opacity)           (PgmViewport *viewport,
                                         guchar opacity);

      PgmError (*set_fullscreen)        (PgmViewport *viewport,
                                         gboolean fullscreen);

      PgmError (*set_iconified)         (PgmViewport *viewport,
                                         gboolean iconified);

      PgmError (*focus)                 (PgmViewport *viewport);

      PgmError (*set_screen_resolution) (PgmViewport *viewport,
                                         gint width,
                                         gint height);
      PgmError (*get_screen_resolution) (PgmViewport *viewport,
                                         gint *width,
                                         gint *height);

      PgmError (*set_screen_size_mm)    (PgmViewport *viewport,
                                         gint width,
                                         gint height);
      PgmError (*get_screen_size_mm)    (PgmViewport *viewport,
                                         gint *width,
                                         gint *height);

      PgmError (*set_canvas)            (PgmViewport *viewport,
                                         PgmCanvas *canvas);

      PgmError (*update_projection)     (PgmViewport *viewport);

      PgmError (*get_embedding_id)      (PgmViewport *viewport,
                                         gulong *embedding_id);

      PgmError (*get_pixel_formats)     (PgmViewport *viewport,
                                         gulong *formats_mask);

      PgmError (*get_caps_mask)         (PgmViewport *viewport,
                                         gulong *caps_mask);

      PgmError (*get_max_texture_size)  (PgmViewport *viewport,
                                         guint32 *max_texture_size);

      PgmError (*get_frame_rate)        (PgmViewport *viewport,
                                         guint *frame_rate);

      PgmError (*set_message_filter)    (PgmViewport *viewport,
                                         GList *filter);

      PgmError (*read_pixels)           (PgmViewport *viewport,
                                         guint x,
                                         guint y,
                                         guint width,
                                         guint height,
                                         guint8 *pixels);

      PgmError (*set_drag_status)       (PgmViewport *viewport,
                                         gboolean accept);
    } PgmViewportClass;

Pigment drawable class.

GstObjectClass `parent_class`; | the parent class structure.
`button_press_event` () | the "button-press-event" signal.
`button_pressure_event` () | the "button-pressure-event" signal.
`button_release_event` () | the "button-release-event" signal.
`key_press_event` () | the "key-press-event" signal.
`key_release_event` () | the "key-release-event" signal.
`configure_event` () | the "configure-event" signal.
`delete_event` () | the "delete-event" signal.
`scroll_event` () | the "scroll-event" signal.
`motion_notify_event` () | the "motion-notify-event" signal.
`expose_event` () | the "expose-event" signal.
`drag_motion_event` () | the "drag-motion-event" signal.
`drag_drop_event` () | the "drag-drop-event" signal.
`drag_leave_event` () | the "drag-leave-event" signal.
`state_event` () | the "state-event" signal.
`win32_message_event` () | the "win32-message-event" signal.
`pixels_read` () | the "pixels-read" signal.
`update_pass` () | the "update-pass" signal.
`set_title` () | the set_title virtual method.
`show` () | the show virtual method.
`hide` () | the hide virtual method.
`set_decorated` () | the set_decorated virtual method.
`set_cursor` () | the set_cursor virtual method.
`set_icon` () | the set_icon virtual method.
`set_size` () | the set_size virtual method.
`get_size` () | the get_size virtual method.
`set_alpha_blending` () | the set_alpha_blending virtual method.
`set_opacity` () | the set_opacity virtual method.
`set_fullscreen` () | the set_fullscreen virtual method.
`set_iconified` () | the set_iconified virtual method.
`focus` () | the focus virtual method.
`set_screen_resolution` () | the set_screen_resolution virtual method.
`get_screen_resolution` () | the get_screen_resolution virtual method.
`set_screen_size_mm` () | the set_screen_size_mm virtual method.
`get_screen_size_mm` () | the get_screen_size_mm virtual method.
`set_canvas` () | the set_canvas virtual method.
`update_projection` () | the update_projection virtual method.
`get_embedding_id` () | the get_embedding_id virtual method.
`get_pixel_formats` () | the get_pixel_formats virtual method.
`get_caps_mask` () | the get_caps_mask virtual method.
`get_max_texture_size` () | the get_max_texture_size virtual method.
`get_frame_rate` () | the get_frame_rate virtual method.
`set_message_filter` () | the set_message_filter virtual method.
`read_pixels` () | the read_pixels virtual method.
`set_drag_status` () | the set_drag_status virtual method.

### pgm_viewport_set_title ()

    PgmError            pgm_viewport_set_title              (PgmViewport *viewport,
                                                             const gchar *title);

Sets the title appearing in the title bar and in the iconified window list. The string is copied and can be freed when the call returns.

MT safe.

`viewport` : | a PgmViewport object.
`title` : | the title.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_title ()

    PgmError            pgm_viewport_get_title              (PgmViewport *viewport,
                                                             gchar **title);

Retrieves the title of `viewport` in `title`.

MT safe.

`viewport` : | a PgmViewport object.
`title` : | a pointer to a pointer to a gchar where the title string will be stored. `g_free()` after use.
Returns : | A PgmError indicating success/failure.

### pgm_viewport_show ()

    PgmError            pgm_viewport_show                   (PgmViewport *viewport);

Makes `viewport` visible.

MT safe.

`viewport` : | a PgmViewport object.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_hide ()

    PgmError            pgm_viewport_hide                   (PgmViewport *viewport);

Makes `viewport` invisible.

MT safe.

`viewport` : | a PgmViewport object.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_is_visible ()

    PgmError            pgm_viewport_is_visible             (PgmViewport *viewport,
                                                             gboolean *visible);

Retrieves whether `viewport` is visible.

MT safe.

`viewport` : | a PgmViewport object.
`visible` : | a pointer to a gboolean where the visible state of the viewport is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_decorated ()

    PgmError            pgm_viewport_set_decorated          (PgmViewport *viewport,
                                                             gboolean decorated);

By default, viewports should be (depending on the plugin) decorated with a title bar and resize controls. This function allows to disable these decorations, creating a borderless viewport.

MT safe.

`viewport` : | a PgmViewport object.
`decorated` : | `TRUE` to decorate the viewport.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_decorated ()

    PgmError            pgm_viewport_get_decorated          (PgmViewport *viewport,
                                                             gboolean *decorated);

Retrieves in `decorated` whether `viewport` is decorated.

MT safe.

`viewport` : | a PgmViewport object.
`decorated` : | a pointer the a gboolean where the decorated state will be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_cursor ()

    PgmError            pgm_viewport_set_cursor             (PgmViewport *viewport,
                                                             PgmViewportCursor cursor);

Sets `cursor` as the current cursor of `viewport`.

MT safe.

`viewport` : | a PgmViewport object.
`cursor` : | the cursor to set.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_cursor ()

    PgmError            pgm_viewport_get_cursor             (PgmViewport *viewport,
                                                             PgmViewportCursor *cursor);

Retrieves the `cursor` of `viewport`.

MT safe.

`viewport` : | a PgmViewport object.
`cursor` : | a pointer PgmViewportCursor where the `viewport` cursor is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_icon ()

    PgmError            pgm_viewport_set_icon               (PgmViewport *viewport,
                                                             GdkPixbuf *icon);

Sets `icon` as the current icon of `viewport` (shown by the window manager e.g. when the `viewport` window is minimised).

MT safe.

`viewport` : | a PgmViewport object.
`icon` : | a GdkPixbuf object to set as icon for `viewport`.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_icon ()

    PgmError            pgm_viewport_get_icon               (PgmViewport *viewport,
                                                             GdkPixbuf **icon);

Retrieves the `icon` of `viewport`.

MT safe.

`viewport` : | a PgmViewport object.
`icon` : | a double pointer GdkPixbuf where the `viewport` icon is going to be stored. Unref after usage.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_size ()

    PgmError            pgm_viewport_set_size               (PgmViewport *viewport,
                                                             gint width,
                                                             gint height);

Sets `viewport` size in pixels to (`width`,`height`).

MT safe.

`viewport` : | a PgmViewport object.
`width` : | the viewport width.
`height` : | the viewport height.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_size ()

    PgmError            pgm_viewport_get_size               (PgmViewport *viewport,
                                                             gint *width,
                                                             gint *height);

Retrieves the size (`width`,`height`) of `viewport` in pixels.

MT safe.

`viewport` : | a PgmViewport object.
`width` : | a pointer to a gint where the viewport width in pixels is going to be stored.
`height` : | a pointer to a gint where the viewport height in pixels is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_alpha_blending ()

    PgmError            pgm_viewport_set_alpha_blending     (PgmViewport *viewport,
                                                             gboolean alpha_blending);

Enable or disable alpha blending on `viewport`.

The function is useful to improve the rendering performance. For instance it can make HD video playback in fullscreen smoother, when no blended drawables need to be drawn over it.

MT safe.

`viewport` : | a PgmViewport object.
`alpha_blending` : | the alpha blending state.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_alpha_blending ()

    PgmError            pgm_viewport_get_alpha_blending     (PgmViewport *viewport,
                                                             gboolean *alpha_blending);

Retrieves in `alpha_blending` the alpha blending state of `viewport`.

MT safe.

`viewport` : | a PgmViewport object.
`alpha_blending` : | a pointer to a gboolean where the alpha blending state is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_opacity ()

    PgmError            pgm_viewport_set_opacity            (PgmViewport *viewport,
                                                             guchar opacity);

Set the opacity of `viewport`.

Note that this function only works if `viewport` supports the PGM_VIEWPORT_OPACITY capacity. The opacity is considered by compositing managers for blending with other applications.

MT safe.

`viewport` : | a PgmViewport object.
`opacity` : | the opacity between 0 and 255.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_opacity ()

    PgmError            pgm_viewport_get_opacity            (PgmViewport *viewport,
                                                             guchar *opacity);

Retrieves in `opacity` the opacity of `viewport`.

MT safe.

`viewport` : | a PgmViewport object.
`opacity` : | a pointer to a guchar where the opacity is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_fullscreen ()

    PgmError            pgm_viewport_set_fullscreen         (PgmViewport *viewport,
                                                             gboolean fullscreen);

Sets/unsets fullscreen mode of `viewport` function of `fullscreen`.

MT safe.

`viewport` : | a PgmViewport object.
`fullscreen` : | the fullscreen state.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_fullscreen ()

    PgmError            pgm_viewport_get_fullscreen         (PgmViewport *viewport,
                                                             gboolean *fullscreen);

Retrieves the fullscreen state of `viewport` in `fullscreen`.

MT safe.

`viewport` : | a PgmViewport object.
`fullscreen` : | a pointer to a gboolean where the fullscreen state is going to be stored.
Returns : | A PgmError indicating success/failure.

### pgm_viewport_set_iconified ()

    PgmError            pgm_viewport_set_iconified          (PgmViewport *viewport,
                                                             gboolean iconified);

Asks to iconify (i.e. minimize) `viewport` depending on the `iconified` value.

MT safe.

`viewport` : | a PgmViewport object.
`iconified` : | `TRUE` to iconify the viewport.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_iconified ()

    PgmError            pgm_viewport_get_iconified          (PgmViewport *viewport,
                                                             gboolean *iconified);

Retrieves in `iconified` whether `viewport` is iconified.

MT safe.

`viewport` : | a PgmViewport object.
`iconified` : | a pointer the a gboolean where the iconified state will be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_focus ()

    PgmError            pgm_viewport_focus                  (PgmViewport *viewport);

Presents `viewport` to the user. This may mean raising the window in the stacking order, deiconifying it and/or giving it the keyboard focus, possibly dependent on the user's platform, window manager, and preferences.

Note that if `viewport` is hidden, this function calls `pgm_viewport_show()` as well.

MT safe.

`viewport` : | a PgmViewport object.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_screen_resolution ()

    PgmError            pgm_viewport_get_screen_resolution  (PgmViewport *viewport,
                                                             gint *width,
                                                             gint *height);

Retrieves the resolution (`width`,`height`) of `viewport` in pixels.

MT safe.

`viewport` : | a PgmViewport object.
`width` : | a pointer to a gint where the screen width in pixels is going to be stored.
`height` : | a pointer to a gint where the screen height in pixels is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_screen_resolution ()

    PgmError            pgm_viewport_set_screen_resolution  (PgmViewport *viewport,
                                                             gint width,
                                                             gint height);

Sets a new resolution (`width`,`height`) of `viewport` in pixels. This is changing the video mode or the display resolution so you are strongly encouraged to restore it to original value when exiting.

MT safe.

`viewport` : | a PgmViewport object.
`width` : | the screen width in pixels.
`height` : | the screen height in pixels.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_screen_size_mm ()

    PgmError            pgm_viewport_get_screen_size_mm     (PgmViewport *viewport,
                                                             gint *width,
                                                             gint *height);

Retrieves the physical (`width`,`height`) size of `viewport` in millimeters. If the plugin can not provide that information it will return -1 as width and height. In that case the application should provide the screen size through `pgm_viewport_set_screen_size_mm()`.

MT safe.

`viewport` : | a PgmViewport object.
`width` : | a pointer to a gint where the screen width in millimeters is going to be stored.
`height` : | a pointer to a gint where the screen height in millimeters is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_screen_size_mm ()

    PgmError            pgm_viewport_set_screen_size_mm     (PgmViewport *viewport,
                                                             gint width,
                                                             gint height);

Sets the physical screen size in millimeters. This is used if the `viewport` implementation cannot retrieve that information by itself. You have to define the physical ratio of the screen so that `viewport` can calculate the pixel aspect ratio.

MT safe.

`viewport` : | a PgmViewport object.
`width` : | the screen width in millimeters.
`height` : | the screen height in millimeters.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_message_filter ()

    PgmError            pgm_viewport_set_message_filter     (PgmViewport *viewport,
                                                             GList *filter);

Sets the list of message types filtered by `viewport` for the "win32-message-events" signal. The previously set filter is discarded. A NULL `filter` is equivalent to a void list. The list is copied internally and have to be freed by the caller.

MT safe.

`viewport` : | a PgmViewport object.
`filter` : | the GList containing the message types to filter.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_message_filter ()

    PgmError            pgm_viewport_get_message_filter     (PgmViewport *viewport,
                                                             GList **filter);

Retrieves the current list of message types filtered by `viewport`.

MT safe.

`viewport` : | a PgmViewport object.
`filter` : | a pointer to GList pointer in which the filter list is going to be stored. `g_list_free()` after use.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_push_event ()

    PgmError            pgm_viewport_push_event             (PgmViewport *viewport,
                                                             PgmEvent *event);

Push an event in the list.

MT safe.

`viewport` : | a PgmViewport object.
`event` : | the PgmEvent to push.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_canvas ()

    PgmError            pgm_viewport_get_canvas             (PgmViewport *viewport,
                                                             PgmCanvas **canvas);

Retrieves the current canvas or NULL if there's no canvas bound.

MT safe.

`viewport` : | a PgmViewport object.
`canvas` : | a pointer to PgmCanvas pointer in which the canvas bound to `viewport` is going to be stored. The refcount of canvas is increased.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_canvas ()

    PgmError            pgm_viewport_set_canvas             (PgmViewport *viewport,
                                                             PgmCanvas *canvas);

Sets the `canvas` to be projected by the `viewport`. This function increases the refcount on the canvas. Any previously set canvas on `viewport` is unreffed. If `canvas` is NULL, the previously set canvas is unreffed.

MT safe.

`viewport` : | a PgmViewport object.
`canvas` : | the PgmCanvas to bind.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_canvas_rotation ()

    PgmError            pgm_viewport_set_canvas_rotation    (PgmViewport *viewport,
                                                             PgmViewportRotation rotation);

Affects the way `viewport` projects its canvas applying the specified `rotation`.

MT safe.

`viewport` : | a PgmViewport object.
`rotation` : | the PgmViewportRotation rotation type.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_canvas_rotation ()

    PgmError            pgm_viewport_get_canvas_rotation    (PgmViewport *viewport,
                                                             PgmViewportRotation *rotation);

Retrieves the current `rotation` applied by `viewport` on its canvas.

MT safe.

`viewport` : | a PgmViewport object.
`rotation` : | a pointer to PgmViewportRotation where the current rotation will be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_set_canvas_reflection ()

    PgmError            pgm_viewport_set_canvas_reflection  (PgmViewport *viewport,
                                                             PgmViewportReflection reflection);

Affects the way `viewport` projects its canvas applying the specified `reflection`.

MT safe.

`viewport` : | a PgmViewport object.
`reflection` : | the PgmViewportReflection reflection type.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_canvas_reflection ()

    PgmError            pgm_viewport_get_canvas_reflection  (PgmViewport *viewport,
                                                             PgmViewportReflection *reflection);

Retrieves the current `reflection` applied by `viewport` on its canvas.

MT safe.

`viewport` : | a PgmViewport object.
`reflection` : | a pointer to PgmViewportReflection where the current reflection will be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_update_projection ()

    PgmError            pgm_viewport_update_projection      (PgmViewport *viewport);

Update the projection. The projection update is done automatically by Pigment, this function is only useful for plugin that have changed for instance the size of the viewport, and want to adapt the projection accordingly.

MT safe.

`viewport` : | a PgmViewport object.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_to_canvas ()

    PgmError            pgm_viewport_to_canvas              (PgmViewport *viewport,
                                                             gfloat *canvas_x,
                                                             gfloat *canvas_y,
                                                             gfloat *canvas_z,
                                                             gfloat viewport_x,
                                                             gfloat viewport_y,
                                                             gfloat viewport_z);

Retrieves the projection of a 3-components vector in viewport coordinates on the viewport in a 3-components vector in canvas coordinates. The z component of the viewport being clamped in the range [0.0, 1.0].

Note that if you want to get a canvas vector with a z coordinates of 0.0f, you can give -1.0f to `viewport_z`. It can be useful when you want to convert 2d position in viewport coordinates to canvas coordinates.

MT safe.

`viewport` : | a PgmViewport object.
`canvas_x` : | a gfloat address to store the unprojected canvas x component.
`canvas_y` : | a gfloat address to store the unprojected canvas y component.
`canvas_z` : | a gfloat address to store the unprojected canvas z component.
`viewport_x` : | the viewport x component to project.
`viewport_y` : | the viewport y component to project.
`viewport_z` : | the viewport z component to project.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_from_canvas ()

    PgmError            pgm_viewport_from_canvas            (PgmViewport *viewport,
                                                             gfloat *viewport_x,
                                                             gfloat *viewport_y,
                                                             gfloat *viewport_z,
                                                             gfloat canvas_x,
                                                             gfloat canvas_y,
                                                             gfloat canvas_z);

Retrieves the projection of a 3-components vector in canvas coordinates on the viewport in a 3-components vector in viewport coordinates.

MT safe.

`viewport` : | a PgmViewport object.
`viewport_x` : | a gfloat address to store the projected viewport x component.
`viewport_y` : | a gfloat address to store the projected viewport y component.
`viewport_z` : | a gfloat address to store the projected viewport z component.
`canvas_x` : | the canvas x component to project.
`canvas_y` : | the canvas y component to project.
`canvas_z` : | the canvas z component to project.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_embedding_id ()

    PgmError            pgm_viewport_get_embedding_id       (PgmViewport *viewport,
                                                             gulong *embedding_id);

Gets the embedding ID of `viewport`. It can be used by other applications to embed it.

MT safe.

`viewport` : | a PgmViewport object.
`embedding_id` : | a pointer to a gulong where the embedding ID is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_pixel_formats ()

    PgmError            pgm_viewport_get_pixel_formats      (PgmViewport *viewport,
                                                             gulong *formats_mask);

Gets the list of supported pixel formats of `viewport`.

MT safe.

`viewport` : | a PgmViewport object.
`formats_mask` : | a pointer to a gulong where the mask of supported PgmImagePixelFormat is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_caps_mask ()

    PgmError            pgm_viewport_get_caps_mask          (PgmViewport *viewport,
                                                             gulong *caps_mask);

Retrieves the mask of supported PgmViewportCapacity.

MT safe.

`viewport` : | a PgmViewport object.
`caps_mask` : | a pointer to a gulong where the mask of PgmViewportCapacity is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_max_texture_size ()

    PgmError            pgm_viewport_get_max_texture_size   (PgmViewport *viewport,
                                                             guint32 *max_texture_size);

Retrieves the maximum texture size.

MT safe.

`viewport` : | a PgmViewport object.
`max_texture_size` : | a pointer to a guint32 where the maximum texture size is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_get_frame_rate ()

    PgmError            pgm_viewport_get_frame_rate         (PgmViewport *viewport,
                                                             guint *frame_rate);

Retrieves the frame rate in frames per second of the rendering of the canvas on `viewport`. The value retrieved changes each second, and represents the number of frames that have been rendered in the previous second.

That function could be useful to check the rendering performance on a system, and for instance tell the user if too many frames are dropped.

MT safe.

`viewport` : | a PgmViewport object.
`frame_rate` : | a pointer to a guint where the frame rate is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_read_pixels ()

    PgmError            pgm_viewport_read_pixels            (PgmViewport *viewport,
                                                             guint x,
                                                             guint y,
                                                             guint width,
                                                             guint height,
                                                             guint8 *pixels);

Requests the reading of a pixel area in `viewport`, starting with the pixel whose top-left corner is at location (`x`, `y`) and dimension is (`width`, `height`). Once the pixel area is obtained, the "pixels-read" signal is emitted with the requested pixels stored at location `pixels`. The retrieved pixel area is in the RGBA color space.

`pixels` should be allocated by the application with the necessary size (width * height * 4) before any call to that function. A callback must be connected to the "pixels-read" signal before any call to that function. `x`, `y`, `width` and `height` are clamped if their values lie outside `viewport` size.

MT Safe.

`viewport` : | a PgmViewport object.
`x` : | the x coordinate of the first pixel to read from the left of `viewport`.
`y` : | the y coordinate of the first pixel to read from the top of `viewport`.
`width` : | the width of the pixel area to read, corresponds to a single pixel.
`height` : | the height of the pixel area to read, corresponds to a single pixel.
`pixels` : | a pre-allocated memory area where the pixels read will be written. The buffer must be freed by the application, in the "pixels-read" signal callback for instance.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_push_pixels ()

    PgmError            pgm_viewport_push_pixels            (PgmViewport *viewport,
                                                             guint width,
                                                             guint height,
                                                             guint8 *pixels);

Push a pixel area to `viewport`. The function will emit the "pixels-read" signal from the Pigment main loop with the given pixel area parameters.

A plugin must call this function for each `read_pixels()` call that does not return an error, because the user may free the pixel array in the callback called from there.

This function should only be used by plugins.

MT safe.

`viewport` : | a PgmViewport object.
`width` : | the width of the pixel area.
`height` : | the height of the pixel area.
`pixels` : | the pixels to push.
Returns : | a PgmError indicating success/failure.

### pgm_viewport_emit_update_pass ()

    PgmError            pgm_viewport_emit_update_pass       (PgmViewport *viewport);

Emits the 'update-pass' signal on `viewport`.

This function should only be used by plugins.

MT safe.

`viewport` : | the PgmViewport object.
Returns : | a PgmError indicating success/failure.

## Signal Details

### The `"button-press-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted on a mouse button press on the `viewport`.

`viewport` : | the PgmViewport
`event` : | the PgmEventButton
`user_data` : | user data set when the signal handler was connected.

### The `"button-pressure-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted on a mouse button pressure change on the `viewport`.

`viewport` : | the PgmViewport
`event` : | the PgmEventButton
`user_data` : | user data set when the signal handler was connected.

### The `"button-release-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted on a mouse button release on the `viewport`.

`viewport` : | the PgmViewport
`event` : | the PgmEventButton
`user_data` : | user data set when the signal handler was connected.

### The `"configure-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted on a `viewport` position or size change.

`viewport` : | the PgmViewport
`event` : | the PgmEventConfigure
`user_data` : | user data set when the signal handler was connected.

### The `"delete-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted on a `viewport` close request (ie the user clicked the close button of the window manager).

`viewport` : | the PgmViewport
`event` : | the PgmEventDelete
`user_data` : | user data set when the signal handler was connected.

### The `"drag-drop-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted when the user drops data onto `viewport`. Note that you have to connect a handler to the signal "drag-motion-event" and return TRUE to accept a drag. This signal is not emitted if a drag has not been accepted.

`viewport` : | the PgmViewport
`event` : | the PgmEventDnd
`user_data` : | user data set when the signal handler was connected.

### The `"drag-leave-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted when the user leaves `viewport` during a drag. A typical reason to connect to this signal is to undo things done in "drag-motion-event".

`viewport` : | the PgmViewport
`event` : | the PgmEventDnd
`user_data` : | user data set when the signal handler was connected.

### The `"drag-motion-event"` signal

    gboolean            user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted when the user moves the cursor over `viewport` during a drag. The signal handler must determine whether the cursor position is in a drop zone or not. If it is not in a drop zone, it returns FALSE and the "drag-drop-event" signal will not be called. Otherwise, the handler returns TRUE.

`viewport` : | the PgmViewport
`event` : | the PgmEventDnd
`user_data` : | user data set when the signal handler was connected.

### The `"expose-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted when the `viewport` visibility status has changed.

`viewport` : | the PgmViewport
`event` : | the PgmEventExpose
`user_data` : | user data set when the signal handler was connected.

### The `"key-press-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted on a keyboard press on the `viewport`.

`viewport` : | the PgmViewport
`event` : | the PgmEventKey
`user_data` : | user data set when the signal handler was connected.

### The `"key-release-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted on a keyboard release on the `viewport`.

`viewport` : | the PgmViewport
`event` : | the PgmEventKey
`user_data` : | user data set when the signal handler was connected.

### The `"motion-notify-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted on a mouse move on the `viewport`.

`viewport` : | the PgmViewport
`event` : | the PgmEventMotion
`user_data` : | user data set when the signal handler was connected.

### The `"pixels-read"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            guint        width,
                                                            guint        height,
                                                            gpointer     pixels,
                                                            gpointer     user_data)      : Run Last

Will be emitted when pixels have been read following a call to `pgm_viewport_read_pixels()`.

`viewport` : | the PgmViewport
`width` : | the width of the pixels area
`height` : | the height of the pixels area
`pixels` : | the pixels area that has been filled. It has been allocated by the application and must be freed by the application.
`user_data` : | user data set when the signal handler was connected.

### The `"scroll-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted on a mouse scroll on the `viewport`.

`viewport` : | the PgmViewport
`event` : | the PgmEventScroll
`user_data` : | user data set when the signal handler was connected.

### The `"state-event"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            PgmEvent    *event,
                                                            gpointer     user_data)      : Run Last

Will be emitted when the state of `viewport` changes, being a visibility change, a fullscreen change or an iconification change.

`viewport` : | the PgmViewport
`event` : | the PgmEventState
`user_data` : | user data set when the signal handler was connected.

### The `"update-pass"` signal

    void                user_function                      (PgmViewport *viewport,
                                                            gpointer     user_data)      : Run Last

Will be emitted prior to any rendering pass happening in the Pigment internal rendering thread. It is highly recommended to update all the Pigment drawables rendered by `viewport` in this signal. It ensures the best performance and rendering correctness since the object update pass will be completely synchronized prior to the rendering pass.

Note that this is the only signal in Pigment which is emitted from another thread than the one of the Pigment main loop.

`viewport` : | the PgmViewport
`user_data` : | user data set when the signal handler was connected.

## See Also

#PgmCanvas, PgmViewportFactory, PgmDrawable.