![]() |
![]() |
![]() |
Pigment 0.3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Signals |
#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);
"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
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)
typedef enum { PGM_VIEWPORT_LEFT_ARROW = 0, PGM_VIEWPORT_INHERIT = 1, PGM_VIEWPORT_NONE = 2 } PgmViewportCursor;
Pigment system cursor type.
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.
Supports accelerated rendering thanks to dedicated hardware. | |
Supports embedding into another application. | |
Supports opacity so that compositing managers can blend the viewport with other applications. | |
Supports touchpad so that application can use the pressure events and parameters. | |
Supports X11 system buffer as image content. Actually, X11 system buffers are Pixmaps. |
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.
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.
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 * |
the factory used to instantiate the PgmViewport. |
PgmCanvas * |
the attached canvas. |
GList * |
the filter of message events. |
gchar * |
the viewport title. |
GdkPixbuf * |
the current icon. |
PgmViewportCursor |
the current cursor. |
gboolean |
the fullscreen state. |
gboolean |
the visible state. |
gboolean |
the decorated state. |
gboolean |
the iconified state. |
gboolean |
the alpha blending state. |
gint |
the viewport width. |
gint |
the viewport height. |
gint |
the viewport screen width in millimeters. |
gint |
the viewport screen height in millimeters. |
PgmMat4x4 * |
the 4x4 projection matrix. |
PgmMat4x4 * |
the 4x4 inverse projection matrix. |
gint |
the attached canvas projected x position. |
gint |
the attached canvas projected y position. |
gint |
the attached canvas projected width. |
gint |
the attached canvas projected height. |
PgmViewportRotation |
the rotation of the projected canvas. |
PgmViewportReflection |
the reflection of the projected canvas. |
gfloat |
the pixel-aspect-ratio. |
gfloat |
the viewport ratio. |
gfloat |
the attached canvas ratio with pixel-aspect-ratio correction applied. |
gulong |
the viewport mask of supported capacities. |
guchar |
the opacity. |
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 |
the parent class structure. |
|
the "button-press-event" signal. |
|
the "button-pressure-event" signal. |
|
the "button-release-event" signal. |
|
the "key-press-event" signal. |
|
the "key-release-event" signal. |
|
the "configure-event" signal. |
|
the "delete-event" signal. |
|
the "scroll-event" signal. |
|
the "motion-notify-event" signal. |
|
the "expose-event" signal. |
|
the "drag-motion-event" signal. |
|
the "drag-drop-event" signal. |
|
the "drag-leave-event" signal. |
|
the "state-event" signal. |
|
the "win32-message-event" signal. |
|
the "pixels-read" signal. |
|
the "update-pass" signal. |
|
the set_title virtual method. |
|
the show virtual method. |
|
the hide virtual method. |
|
the set_decorated virtual method. |
|
the set_cursor virtual method. |
|
the set_icon virtual method. |
|
the set_size virtual method. |
|
the get_size virtual method. |
|
the set_alpha_blending virtual method. |
|
the set_opacity virtual method. |
|
the set_fullscreen virtual method. |
|
the set_iconified virtual method. |
|
the focus virtual method. |
|
the set_screen_resolution virtual method. |
|
the get_screen_resolution virtual method. |
|
the set_screen_size_mm virtual method. |
|
the get_screen_size_mm virtual method. |
|
the set_canvas virtual method. |
|
the update_projection virtual method. |
|
the get_embedding_id virtual method. |
|
the get_pixel_formats virtual method. |
|
the get_caps_mask virtual method. |
|
the get_max_texture_size virtual method. |
|
the get_frame_rate virtual method. |
|
the set_message_filter virtual method. |
|
the read_pixels virtual method. |
|
the set_drag_status virtual method. |
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.
|
a PgmViewport object. |
|
the title. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_title (PgmViewport *viewport, gchar **title);
Retrieves the title of viewport
in title
.
MT safe.
|
a PgmViewport object. |
|
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. |
PgmError pgm_viewport_show (PgmViewport *viewport);
Makes viewport
visible.
MT safe.
|
a PgmViewport object. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_hide (PgmViewport *viewport);
Makes viewport
invisible.
MT safe.
|
a PgmViewport object. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_is_visible (PgmViewport *viewport, gboolean *visible);
Retrieves whether viewport
is visible.
MT safe.
|
a PgmViewport object. |
|
a pointer to a gboolean where the visible state of the viewport is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
TRUE to decorate the viewport.
|
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_decorated (PgmViewport *viewport, gboolean *decorated);
Retrieves in decorated
whether viewport
is decorated.
MT safe.
|
a PgmViewport object. |
|
a pointer the a gboolean where the decorated state will be stored. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_set_cursor (PgmViewport *viewport, PgmViewportCursor cursor);
Sets cursor
as the current cursor of viewport
.
MT safe.
|
a PgmViewport object. |
|
the cursor to set. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_cursor (PgmViewport *viewport, PgmViewportCursor *cursor);
Retrieves the cursor
of viewport
.
MT safe.
|
a PgmViewport object. |
|
a pointer PgmViewportCursor where the viewport cursor is going
to be stored.
|
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
a GdkPixbuf object to set as icon for viewport .
|
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_icon (PgmViewport *viewport, GdkPixbuf **icon);
Retrieves the icon
of viewport
.
MT safe.
|
a PgmViewport object. |
|
a double pointer GdkPixbuf where the viewport icon is going
to be stored. Unref after usage.
|
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_set_size (PgmViewport *viewport, gint width, gint height);
Sets viewport
size in pixels to (width
,height
).
MT safe.
|
a PgmViewport object. |
|
the viewport width. |
|
the viewport height. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_size (PgmViewport *viewport, gint *width, gint *height);
Retrieves the size (width
,height
) of viewport
in pixels.
MT safe.
|
a PgmViewport object. |
|
a pointer to a gint where the viewport width in pixels is going to be stored. |
|
a pointer to a gint where the viewport height in pixels is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
the alpha blending state. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_alpha_blending (PgmViewport *viewport, gboolean *alpha_blending);
Retrieves in alpha_blending
the alpha blending state of viewport
.
MT safe.
|
a PgmViewport object. |
|
a pointer to a gboolean where the alpha blending state is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
the opacity between 0 and 255. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_opacity (PgmViewport *viewport, guchar *opacity);
Retrieves in opacity
the opacity of viewport
.
MT safe.
|
a PgmViewport object. |
|
a pointer to a guchar where the opacity is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_set_fullscreen (PgmViewport *viewport, gboolean fullscreen);
Sets/unsets fullscreen mode of viewport
function of fullscreen
.
MT safe.
|
a PgmViewport object. |
|
the fullscreen state. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_fullscreen (PgmViewport *viewport, gboolean *fullscreen);
Retrieves the fullscreen state of viewport
in fullscreen
.
MT safe.
|
a PgmViewport object. |
|
a pointer to a gboolean where the fullscreen state is going to be stored. |
Returns : |
A PgmError indicating success/failure. |
PgmError pgm_viewport_set_iconified (PgmViewport *viewport, gboolean iconified);
Asks to iconify (i.e. minimize) viewport
depending on the iconified
value.
MT safe.
|
a PgmViewport object. |
|
TRUE to iconify the viewport.
|
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_iconified (PgmViewport *viewport, gboolean *iconified);
Retrieves in iconified
whether viewport
is iconified.
MT safe.
|
a PgmViewport object. |
|
a pointer the a gboolean where the iconified state will be stored. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_screen_resolution (PgmViewport *viewport, gint *width, gint *height);
Retrieves the resolution (width
,height
) of viewport
in pixels.
MT safe.
|
a PgmViewport object. |
|
a pointer to a gint where the screen width in pixels is going to be stored. |
|
a pointer to a gint where the screen height in pixels is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
the screen width in pixels. |
|
the screen height in pixels. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
a pointer to a gint where the screen width in millimeters is going to be stored. |
|
a pointer to a gint where the screen height in millimeters is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
the screen width in millimeters. |
|
the screen height in millimeters. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
the GList containing the message types to filter. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_message_filter (PgmViewport *viewport, GList **filter);
Retrieves the current list of message types filtered by viewport
.
MT safe.
|
a PgmViewport object. |
|
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. |
PgmError pgm_viewport_push_event (PgmViewport *viewport, PgmEvent *event);
Push an event in the list.
MT safe.
|
a PgmViewport object. |
|
the PgmEvent to push. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_canvas (PgmViewport *viewport, PgmCanvas **canvas);
Retrieves the current canvas or NULL if there's no canvas bound.
MT safe.
|
a PgmViewport object. |
|
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. |
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.
|
a PgmViewport object. |
|
the PgmCanvas to bind. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_set_canvas_rotation (PgmViewport *viewport, PgmViewportRotation rotation);
Affects the way viewport
projects its canvas applying the specified rotation
.
MT safe.
|
a PgmViewport object. |
|
the PgmViewportRotation rotation type. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_canvas_rotation (PgmViewport *viewport, PgmViewportRotation *rotation);
Retrieves the current rotation
applied by viewport
on its canvas.
MT safe.
|
a PgmViewport object. |
|
a pointer to PgmViewportRotation where the current rotation will be stored. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_set_canvas_reflection (PgmViewport *viewport, PgmViewportReflection reflection);
Affects the way viewport
projects its canvas applying the specified
reflection
.
MT safe.
|
a PgmViewport object. |
|
the PgmViewportReflection reflection type. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_canvas_reflection (PgmViewport *viewport, PgmViewportReflection *reflection);
Retrieves the current reflection
applied by viewport
on its canvas.
MT safe.
|
a PgmViewport object. |
|
a pointer to PgmViewportReflection where the current reflection will be stored. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
a gfloat address to store the unprojected canvas x component. |
|
a gfloat address to store the unprojected canvas y component. |
|
a gfloat address to store the unprojected canvas z component. |
|
the viewport x component to project. |
|
the viewport y component to project. |
|
the viewport z component to project. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
a gfloat address to store the projected viewport x component. |
|
a gfloat address to store the projected viewport y component. |
|
a gfloat address to store the projected viewport z component. |
|
the canvas x component to project. |
|
the canvas y component to project. |
|
the canvas z component to project. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
a pointer to a gulong where the embedding ID is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_pixel_formats (PgmViewport *viewport, gulong *formats_mask);
Gets the list of supported pixel formats of viewport
.
MT safe.
|
a PgmViewport object. |
|
a pointer to a gulong where the mask of supported PgmImagePixelFormat is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_caps_mask (PgmViewport *viewport, gulong *caps_mask);
Retrieves the mask of supported PgmViewportCapacity.
MT safe.
|
a PgmViewport object. |
|
a pointer to a gulong where the mask of PgmViewportCapacity is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
PgmError pgm_viewport_get_max_texture_size (PgmViewport *viewport, guint32 *max_texture_size);
Retrieves the maximum texture size.
MT safe.
|
a PgmViewport object. |
|
a pointer to a guint32 where the maximum texture size is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
a pointer to a guint where the frame rate is going to be stored. |
Returns : |
a PgmError indicating success/failure. |
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.
|
a PgmViewport object. |
|
the x coordinate of the first pixel to read from the left of viewport .
|
|
the y coordinate of the first pixel to read from the top of viewport .
|
|
the width of the pixel area to read, corresponds to a single pixel. |
|
the height of the pixel area to read, corresponds to a single pixel. |
|
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. |
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.
|
a PgmViewport object. |
|
the width of the pixel area. |
|
the height of the pixel area. |
|
the pixels to push. |
Returns : |
a PgmError indicating success/failure. |
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.
|
the PgmViewport object. |
Returns : |
a PgmError indicating success/failure. |
"button-press-event"
signalvoid user_function (PgmViewport *viewport, PgmEvent *event, gpointer user_data) : Run Last
Will be emitted on a mouse button press on the viewport
.
|
the PgmViewport |
|
the PgmEventButton |
|
user data set when the signal handler was connected. |
"button-pressure-event"
signalvoid user_function (PgmViewport *viewport, PgmEvent *event, gpointer user_data) : Run Last
Will be emitted on a mouse button pressure change on the viewport
.
|
the PgmViewport |
|
the PgmEventButton |
|
user data set when the signal handler was connected. |
"button-release-event"
signalvoid user_function (PgmViewport *viewport, PgmEvent *event, gpointer user_data) : Run Last
Will be emitted on a mouse button release on the viewport
.
|
the PgmViewport |
|
the PgmEventButton |
|
user data set when the signal handler was connected. |
"configure-event"
signalvoid user_function (PgmViewport *viewport, PgmEvent *event, gpointer user_data) : Run Last
Will be emitted on a viewport
position or size change.
|
the PgmViewport |
|
the PgmEventConfigure |
|
user data set when the signal handler was connected. |
"delete-event"
signalvoid 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).
|
the PgmViewport |
|
the PgmEventDelete |
|
user data set when the signal handler was connected. |
"drag-drop-event"
signalvoid 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.
|
the PgmViewport |
|
the PgmEventDnd |
|
user data set when the signal handler was connected. |
"drag-leave-event"
signalvoid 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".
|
the PgmViewport |
|
the PgmEventDnd |
|
user data set when the signal handler was connected. |
"drag-motion-event"
signalgboolean 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.
|
the PgmViewport |
|
the PgmEventDnd |
|
user data set when the signal handler was connected. |
"expose-event"
signalvoid user_function (PgmViewport *viewport, PgmEvent *event, gpointer user_data) : Run Last
Will be emitted when the viewport
visibility status has changed.
|
the PgmViewport |
|
the PgmEventExpose |
|
user data set when the signal handler was connected. |
"key-press-event"
signalvoid user_function (PgmViewport *viewport, PgmEvent *event, gpointer user_data) : Run Last
Will be emitted on a keyboard press on the viewport
.
|
the PgmViewport |
|
the PgmEventKey |
|
user data set when the signal handler was connected. |
"key-release-event"
signalvoid user_function (PgmViewport *viewport, PgmEvent *event, gpointer user_data) : Run Last
Will be emitted on a keyboard release on the viewport
.
|
the PgmViewport |
|
the PgmEventKey |
|
user data set when the signal handler was connected. |
"motion-notify-event"
signalvoid user_function (PgmViewport *viewport, PgmEvent *event, gpointer user_data) : Run Last
Will be emitted on a mouse move on the viewport
.
|
the PgmViewport |
|
the PgmEventMotion |
|
user data set when the signal handler was connected. |
"pixels-read"
signalvoid 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()
.
|
the PgmViewport |
|
the width of the pixels area |
|
the height of the pixels area |
|
the pixels area that has been filled. It has been allocated by the application and must be freed by the application. |
|
user data set when the signal handler was connected. |
"scroll-event"
signalvoid user_function (PgmViewport *viewport, PgmEvent *event, gpointer user_data) : Run Last
Will be emitted on a mouse scroll on the viewport
.
|
the PgmViewport |
|
the PgmEventScroll |
|
user data set when the signal handler was connected. |
"state-event"
signalvoid 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.
|
the PgmViewport |
|
the PgmEventState |
|
user data set when the signal handler was connected. |
"update-pass"
signalvoid 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.
|
the PgmViewport |
|
user data set when the signal handler was connected. |