![]() |
![]() |
![]() |
Pigment 0.3 Reference Manual | ![]() |
---|---|---|---|---|
#include <pgm/pgm.h> enum PgmViewportCursor; enum PgmViewportCapacity; PgmViewport; PgmViewportClass; #define PGM_VIEWPORT_HAS_CAPS (viewport,mask) PgmError pgm_viewport_update (PgmViewport *viewport); 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_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_fullscreen (PgmViewport *viewport, gboolean fullscreen); PgmError pgm_viewport_get_fullscreen (PgmViewport *viewport, gboolean *fullscreen); 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_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_update_projection (PgmViewport *viewport); PgmError pgm_viewport_to_canvas (PgmViewport *viewport, gfloat *viewport_x, gfloat *viewport_y, gfloat *viewport_z, gfloat canvas_x, gfloat canvas_y, gfloat canvas_z); PgmError pgm_viewport_from_canvas (PgmViewport *viewport, gfloat *canvas_x, gfloat *canvas_y, gfloat *canvas_z, gfloat viewport_x, gfloat viewport_y, gfloat viewport_z); PgmError pgm_viewport_get_pixel_formats (PgmViewport *viewport, gulong *formats_mask); PgmError pgm_viewport_get_caps_mask (PgmViewport *viewport, gulong *caps_mask);
"button-press-event" : Run Last "button-release-event" : Run Last "configure-event" : Run Last "delete-event" : Run Last "expose-event" : Run Last "key-press-event" : Run Last "key-release-event" : Run Last "motion-notify-event" : Run Last "scroll-event" : 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, you can check that a
mask of capacities is handled thanks to the PGM_VIEWPORT_HAS_CAPS()
macro,
and you can get the list of handled color spaces with the
pgm_viewport_get_pixel_formats()
method.
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.
You are also responsible of the update of the viewport and you have to call
the pgm_viewport_update()
method to force the refresh of the projection of
the canvas on the viewport. You can call this function after each bunch of
changes on your drawables, but you can also add a dedicated timeout to update
your viewport using g_timeout_add()
.
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), } PgmViewportCapacity;
Capacities supported by the viewport.
typedef struct { PgmViewportFactory *factory; PgmCanvas *canvas; gchar *title; PgmViewportCursor cursor; GdkPixbuf *icon; gboolean fullscreen; gboolean visible; gint width, height; gint width_mm, height_mm; PgmMat4x4 projection, inv_projection; gint projected_x, projected_y; gint projected_width, projected_height; gfloat pixel_aspect_ratio; gfloat viewport_ratio; gfloat canvas_ratio; gulong caps_mask; } PgmViewport;
The PgmViewport structure.
PgmViewportFactory *factory ; |
the factory used to instantiate the PgmViewport. |
PgmCanvas *canvas ; |
the attached canvas. |
gchar *title ; |
the viewport title. |
PgmViewportCursor cursor ; |
the current cursor. |
GdkPixbuf *icon ; |
the current icon. |
gboolean fullscreen ; |
the fullscreen state. |
gboolean visible ; |
the visible 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. |
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. |
typedef struct { GstObjectClass parent_class; /* signals */ void (*button_press_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, PgmEventDelete *event); void (*scroll_event) (PgmViewport *viewport, PgmEventScroll *event); void (*motion_notify_event) (PgmViewport *viewport, PgmEventMotion *event); void (*expose_event) (PgmViewport *viewport, PgmEventExpose *event); /* virtual methods for subclasses */ PgmError (*update) (PgmViewport *viewport); PgmError (*set_title) (PgmViewport *viewport, const gchar *title); PgmError (*show) (PgmViewport *viewport); PgmError (*hide) (PgmViewport *viewport); 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_fullscreen) (PgmViewport *viewport, gboolean fullscreen); PgmError (*get_fullscreen) (PgmViewport *viewport, gboolean *fullscreen); 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_pixel_formats) (PgmViewport *viewport, gulong *formats_mask); PgmError (*get_caps_mask) (PgmViewport *viewport, gulong *caps_mask); } PgmViewportClass;
Pigment drawable class.
GstObjectClass parent_class ; |
the parent class structure. |
button_press_event () |
the "button-press-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. |
update () |
the update virtual method. |
set_title () |
the set_title virtual method. |
show () |
the show virtual method. |
hide () |
the hide 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_fullscreen () |
the set_fullscreen virtual method. |
get_fullscreen () |
the get_fullscreen 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_pixel_formats () |
the get_pixel_formats virtual method. |
get_caps_mask () |
the get_caps_mask virtual method. |
#define PGM_VIEWPORT_HAS_CAPS(viewport,mask)
Retrieves whether viewport
supports the mask
of PgmViewportCapacity.
viewport : |
a PgmViewport object. |
mask : |
the PgmViewportCapacity to check, can be a mask of capacities. |
PgmError pgm_viewport_update (PgmViewport *viewport);
Redraws all the Drawable owned by the canvas on the viewport
.
MT safe.
viewport : |
a PgmViewport object. |
Returns : | a PgmError indicating success/failure. |
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. |
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. |
PgmError pgm_viewport_show (PgmViewport *viewport);
Makes viewport
visible.
MT safe.
viewport : |
a PgmViewport object. |
Returns : | a PgmError indicating success/failure. |
PgmError pgm_viewport_hide (PgmViewport *viewport);
Makes viewport
invisible.
MT safe.
viewport : |
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.
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. |
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. |
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. |
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. |
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.
|
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.
viewport : |
a PgmViewport object. |
width : |
the viewport width. |
height : |
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.
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
PgmError pgm_viewport_to_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 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].
MT safe.
viewport : |
a PgmViewport object. |
viewport_x : |
the viewport x component to project. |
viewport_y : |
the viewport y component to project. |
viewport_z : |
the viewport z component to project. |
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. |
Returns : | a PgmError indicating success/failure. |
PgmError pgm_viewport_from_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 canvas coordinates on the viewport in a 3-components vector in viewport coordinates.
MT safe.
viewport : |
a PgmViewport object. |
canvas_x : |
the canvas x component to project. |
canvas_y : |
the canvas y component to project. |
canvas_z : |
the canvas z component to project. |
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. |
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.
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |