fdo-mirrors/cairo
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/cairo/cairo.git synced 2026-05-06 05:48:00 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

[os2] Improve documentation

Browse source 
Move the API documentation for the OS/2 backend from the .h file to the .c file and use the correct format.
This commit is contained in:
Peter Weilbacher 2008-02-07 00:03:33 +01:00
parent bf1f7f70b6
commit c11b036b75
2 changed files with 139 additions and 115 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

139
src/cairo-os2-surface.c
View file

@ -86,6 +86,16 @@ DisableFPUException (void)
_control87 (usCW, MCW_EM | 0x80);
}
/**
* cairo_os2_init:
*
* Initializes the Cairo library. This function is automatically called if
* Cairo was compiled to be a DLL (however it's not a problem if it's called
* multiple times). But if you link to Cairo statically, you have to call it
* once to set up Cairo's internal structures and mutexes.
*
* Since: 1.4
**/
cairo_public void
cairo_os2_init (void)
{
@ -102,6 +112,16 @@ cairo_os2_init (void)
CAIRO_MUTEX_INITIALIZE ();
}
/**
* cairo_os2_fini:
*
* Uninitializes the Cairo library. This function is automatically called if
* Cairo was compiled to be a DLL (however it's not a problem if it's called
* multiple times). But if you link to Cairo statically, you have to call it
* once to shut down Cairo, to let it free all the resources it has allocated.
*
* Since: 1.4
**/
cairo_public void
cairo_os2_fini (void)
{
@ -716,6 +736,26 @@ _cairo_os2_surface_get_extents (void *abstract_surface,
return CAIRO_STATUS_SUCCESS;
}
/**
* cairo_os2_surface_create:
* @hps_client_window: the presentation handle to bind the surface to
* @width: the width of the surface
* @height: the height of the surface
*
* Create a Cairo surface which is bound to a given presentation space (HPS).
* The surface will be created to have the given size.
* By default every change to the surface will be made visible immediately by
* blitting it into the window. This can be changed with
* cairo_os2_surface_set_manual_window_refresh().
* Note that the surface will contain garbage when created, so the pixels have
* to be initialized by hand first. You can use the Cairo functions to fill it
* with black, or use cairo_surface_mark_dirty() to fill the surface with pixels
* from the window/HPS.
*
* Return value: the newly created surface
*
* Since: 1.4
**/
cairo_surface_t *
cairo_os2_surface_create (HPS hps_client_window,
int width,
@ -814,6 +854,31 @@ cairo_os2_surface_create (HPS hps_client_window,
return (cairo_surface_t *)local_os2_surface;
}
/**
* cairo_os2_surface_set_size:
* @surface: the cairo surface to resize
* @new_width: the new width of the surface
* @new_height: the new height of the surface
* @timeout: timeout value in milliseconds
*
* When the client window is resized, call this API to set the new size in the
* underlying surface accordingly. This function will reallocate everything,
* so you'll have to redraw everything in the surface after this call.
* The surface will contain garbage after the resizing. So the notes of
* cairo_os2_surface_create() apply here, too.
*
* The timeout value specifies how long the function should wait on other parts
* of the program to release the buffers. It is necessary, because it can happen
* that Cairo is just drawing something into the surface while we want to
* destroy and recreate it.
*
* Return value: %CAIRO_STATUS_SUCCESS if the surface could be resized,
* %CAIRO_STATUS_SURFACE_TYPE_MISMATCH if the surface is not an OS/2 surface,
* %CAIRO_STATUS_NO_MEMORY if the new size could not be allocated, for invalid
* sizes, or if the timeout happened before all the buffers were released
*
* Since: 1.4
**/
int
cairo_os2_surface_set_size (cairo_surface_t *surface,
int new_width,
@ -921,6 +986,31 @@ cairo_os2_surface_set_size (cairo_surface_t *surface,
return CAIRO_STATUS_SUCCESS;
}
/**
* cairo_os2_surface_refresh_window:
* @surface: the cairo surface to refresh
* @hps_begin_paint: the presentation handle of the window to refresh
* @prcl_begin_paint_rect: the rectangle to redraw
*
* This function can be used to force a repaint of a given area of the client
* window. It should usually be called from the WM_PAINT processing of the
* window procedure. However, it can be called any time a given part of the
* window has to be updated.
*
* The HPS and RECTL to be passed can be taken from the usual WinBeginPaint call
* of the window procedure, but you can also get the HPS using WinGetPS, and you
* can assemble your own update rectangle by hand.
* If hps_begin_paint is %NULL, the function will use the HPS passed into
* cairo_os2_surface_create(). If @prcl_begin_paint_rect is %NULL, the function
* will query the current window size and repaint the whole window.
*
* Cairo assumes that if you set the HWND to the surface using
* cairo_os2_surface_set_hwnd(), this function will be called by the application
* every time it gets a WM_PAINT for that HWND. If the HWND is set in the
* surface, Cairo uses this function to handle dirty areas too.
*
* Since: 1.4
**/
void
cairo_os2_surface_refresh_window (cairo_surface_t *surface,
HPS hps_begin_paint,
@ -1018,6 +1108,28 @@ _cairo_os2_surface_finish (void *abstract_surface)
return CAIRO_STATUS_SUCCESS;
}
/**
* cairo_os2_surface_set_hwnd:
* @surface: the cairo surface to associate with the window handle
* @hwnd_client_window: the window handle of the client window
*
* Sets window handle for surface. If Cairo wants to blit into the window
* because it is set to blit as the surface changes (see
* cairo_os2_surface_set_manual_window_refresh()), then there are two ways it
* can choose:
* If it knows the HWND of the surface, then it invalidates that area, so the
* application will get a WM_PAINT message and it can call
* cairo_os2_surface_refresh_window() to redraw that area. Otherwise cairo itself
* will use the HPS it got at surface creation time, and blit the pixels itself.
* It's also a solution, but experience shows that if this happens from a non-PM
* thread, then it can screw up PM internals.
*
* So, best solution is to set the HWND for the surface after the surface
* creation, so every blit will be done from application's message processing
* loop, which is the safest way to do.
*
* Since: 1.4
**/
void
cairo_os2_surface_set_hwnd (cairo_surface_t *surface,
HWND hwnd_client_window)
@ -1044,6 +1156,25 @@ cairo_os2_surface_set_hwnd (cairo_surface_t *surface,
DosReleaseMutexSem (local_os2_surface->hmtx_use_private_fields);
}
/**
* cairo_os2_surface_set_manual_window_refresh:
* @surface: the cairo surface to set the refresh mode for
* @manual_refresh: the switch for manual surface refresh
*
* This API can tell Cairo if it should show every change to this surface
* immediately in the window or if it should be cached and will only be visible
* once the user calls cairo_os2_surface_refresh_window() explicitly. If the
* HWND was not set in the cairo surface, then the HPS will be used to blit the
* graphics. Otherwise it will invalidate the given window region so the user
* will get the WM_PAINT message to redraw that area of the window.
*
* So, if you're only interested in displaying the final result after several
* drawing operations, you might get better performance if you put the surface
* into manual refresh mode by passing a true value to this function. Then call
* cairo_os2_surface_refresh() whenever desired.
*
* Since: 1.4
**/
void
cairo_os2_surface_set_manual_window_refresh (cairo_surface_t *surface,
cairo_bool_t manual_refresh)
@ -1061,6 +1192,14 @@ cairo_os2_surface_set_manual_window_refresh (cairo_surface_t *surface,
local_os2_surface->blit_as_changes = !manual_refresh;
}
/**
* cairo_os2_surface_get_manual_window_refresh:
* @surface: the cairo surface to query the refresh mode from
*
* Return value: current refresh mode of the surface (true by default)
*
* Since: 1.4
**/
cairo_bool_t
cairo_os2_surface_get_manual_window_refresh (cairo_surface_t *surface)
{

115
src/cairo-os2.h
View file

@ -44,153 +44,38 @@ CAIRO_BEGIN_DECLS
/* The OS/2 Specific Cairo API */
/* cairo_os2_init () : */
/* */
/* Initializes the Cairo library. This function is automatically */
/* called if Cairo was compiled to be a DLL (however it's not a */
/* problem if it's called multiple times), but if you link to */
/* Cairo statically, you have to call it once to set up Cairo's */
/* internal structures and mutexes. */
cairo_public void
cairo_os2_init (void);
/* cairo_os2_fini () : */
/* */
/* Uninitializes the Cairo library. This function is automatically */
/* called if Cairo was compiled to be a DLL (however it's not a */
/* problem if it's called multiple times), but if you link to */
/* Cairo statically, you have to call it once to shut down Cairo, */
/* to let it free all the resources it has allocated. */
cairo_public void
cairo_os2_fini (void);
#if CAIRO_HAS_OS2_SURFACE
/* cairo_os2_surface_create () : */
/* */
/* Create a Cairo surface which is bounded to a given presentation */
/* space (HPS). The surface will be created to have the given */
/* size. */
/* By default: Every change to the surface will be made visible */
/* immediately by blitting it into the window. This */
/* can be changed with the */
/* cairo_os2_surface_set_manual_window_refresh () API. */
/* Note that the surface will contain garbage when created, so the */
/* pixels have to be initialized by hand first. You can use the */
/* Cairo functions to fill it with black, or use the */
/* cairo_surface_mark_dirty () API to fill the surface with pixels */
/* from the window/HPS. */
cairo_public cairo_surface_t *
cairo_os2_surface_create (HPS hps_client_window,
int width,
int height);
/* cairo_os2_surface_set_hwnd () : */
/* */
/* Sets window handle for surface. If Cairo wants to blit into the */
/* window because it's set that it should blit as the surface */
/* changes (see cairo_os2_surface_set_manual_window_refresh () API),*/
/* then there are two ways it can choose: */
/* If it knows the HWND of the surface, then it invalidates that */
/* area, so the application will get a WM_PAINT message and it can */
/* call cairo_os2_surface_refresh_window () to redraw that area. */
/* Otherwise cairo itself will use the HPS it got at surface */
/* creation time, and blit the pixels itself. */
/* It's also a solution, but experience shows that if this happens */
/* from a non-PM thread, then it can screw up PM internals. */
/* */
/* So, best solution is to set the HWND for the surface after the */
/* surface creation, so every blit will be done from application's */
/* message processing loop, which is the safest way to do. */
cairo_public void
cairo_os2_surface_set_hwnd (cairo_surface_t *surface,
HWND hwnd_client_window);
/* cairo_os2_surface_set_size () : */
/* */
/* When the client window is resized, call this API so the */
/* underlaying surface will also be resized. This function will */
/* reallocate everything, so you'll have to redraw everything in */
/* the surface after this call. */
/* The surface will contain garbage after the resizing, just like */
/* after cairo_os2_surface_create (), so all those notes also apply */
/* here, please read that! */
/* */
/* The timeout value is in milliseconds, and tells how much the */
/* function should wait on other parts of the program to release */
/* the buffers. It is necessary, because it can be that Cairo is */
/* just drawing something into the surface while we want to */
/* destroy and recreate it. */
/* Returns %CAIRO_STATUS_SUCCESS if the surface could be resized, */
/* or returns other error code if */
/* - the surface is not a real OS/2 Surface */
/* - there is not enough memory to resize the surface */
/* - waiting for all the buffers to be released timed out */
cairo_public int
cairo_os2_surface_set_size (cairo_surface_t *surface,
int new_width,
int new_height,
int timeout);
/* cairo_os2_surface_refresh_window () : */
/* */
/* This function can be used to force a repaint of a given area */
/* of the client window. Most of the time it is called from the */
/* WM_PAINT processing of the window proc. However, it can be */
/* called anytime if a given part of the window has to be updated. */
/* */
/* The function expects a HPS of the window, and a RECTL to tell */
/* which part of the window should be redrawn. */
/* The returned values of WinBeginPaint () is just perfect here, */
/* but you can also get the HPS by using the WinGetPS () function, */
/* and you can assemble your own update rect by hand. */
/* If the hps_begin_paint parameter is %NULL, the function will use */
/* the HPS you passed in to cairo_os2_surface_create (). If the */
/* prcl_begin_paint_rect parameter is %NULL, the function will query */
/* the current window size and repaint the whole window. */
/* */
/* Cairo/2 assumes that if you told the HWND to the surface using */
/* the cairo_os2_surface_set_hwnd () API, then this function will */
/* be called by the application every time it gets a WM_PAINT for */
/* that HWND. If the HWND is told to the surface, Cairo uses this */
/* function to handle dirty areas too, so you were warned. :) */
cairo_public void
cairo_os2_surface_refresh_window (cairo_surface_t *surface,
HPS hps_begin_paint,
PRECTL prcl_begin_paint_rect);
/* cairo_os2_surface_set_manual_window_refresh () : */
/* */
/* This API can tell Cairo if it should show every change to this */
/* surface immediately in the window, or if it should be cached */
/* and will only be visible if the user calls the */
/* cairo_os2_surface_refresh_window () API explicitly. */
/* If the HWND was not told to Cairo, then it will use the HPS to */
/* blit the graphics. Otherwise it will invalidate the given */
/* window region so the user will get WM_PAINT to redraw that area */
/* of the window. */
/* */
/* So, if you're only interested in displaying the final result */
/* after several drawing operations, you might get better */
/* performance if you put the surface into a manual refresh mode */
/* by passing a true value to cairo_os2_surface_set_manual_refresh()*/
/* and then calling cairo_os2_surface_refresh() whenever desired. */
cairo_public void
cairo_os2_surface_set_manual_window_refresh (cairo_surface_t *surface,
cairo_bool_t manual_refresh);
/* cairo_os2_surface_get_manual_window_refresh () : */
/* */
/* This API can return the current mode of the surface. It is */
/* TRUE by default. */
cairo_public cairo_bool_t
cairo_os2_surface_get_manual_window_refresh (cairo_surface_t *surface);