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.