Back to index

lightning-sunbird  0.9+nobinonly
cairo-os2.h
Go to the documentation of this file.
00001 /* cairo - a vector graphics library with display and print output
00002  *
00003  * Copyright © 2005 Red Hat, Inc
00004  *
00005  * This library is free software; you can redistribute it and/or
00006  * modify it either under the terms of the GNU Lesser General Public
00007  * License version 2.1 as published by the Free Software Foundation
00008  * (the "LGPL") or, at your option, under the terms of the Mozilla
00009  * Public License Version 1.1 (the "MPL"). If you do not alter this
00010  * notice, a recipient may use your version of this file under either
00011  * the MPL or the LGPL.
00012  *
00013  * You should have received a copy of the LGPL along with this library
00014  * in the file COPYING-LGPL-2.1; if not, write to the Free Software
00015  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
00016  * You should have received a copy of the MPL along with this library
00017  * in the file COPYING-MPL-1.1
00018  *
00019  * The contents of this file are subject to the Mozilla Public License
00020  * Version 1.1 (the "License"); you may not use this file except in
00021  * compliance with the License. You may obtain a copy of the License at
00022  * http://www.mozilla.org/MPL/
00023  *
00024  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
00025  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
00026  * the specific language governing rights and limitations.
00027  *
00028  * The Original Code is the cairo graphics library.
00029  *
00030  * The Initial Developer of the Original Code is Red Hat, Inc.
00031  *
00032  * Contributor(s):
00033  *     Doodle <doodle@scenergy.dfmk.hu>
00034  */
00035 
00036 #ifndef _CAIRO_OS2_H_
00037 #define _CAIRO_OS2_H_
00038 
00039 #include <cairo.h>
00040 
00041 CAIRO_BEGIN_DECLS
00042 
00043 /* The OS/2 Specific Cairo API */
00044 
00045 /* cairo_os2_initialize() :                                       */
00046 /*                                                                */
00047 /* Initializes the Cairo library. This function is automatically  */
00048 /* called if Cairo was compiled to be a DLL (however it's not a   */
00049 /* problem if it's called multiple times), but if you link to     */
00050 /* Cairo statically, you have to call it once to set up Cairo's   */
00051 /* internal structures and mutexes.                               */
00052 
00053 void
00054 cairo_os2_initialize (void);
00055 
00056 /* cairo_os2_uninitialize() :                                     */
00057 /*                                                                */
00058 /* Uninitializes the Cairo library. This function is automatically*/
00059 /* called if Cairo was compiled to be a DLL (however it's not a   */
00060 /* problem if it's called multiple times), but if you link to     */
00061 /* Cairo statically, you have to call it once to shut down Cairo, */
00062 /* to let it free all the resources it has allocated.             */
00063 
00064 void
00065 cairo_os2_uninitialize (void);
00066 
00067 #if CAIRO_HAS_OS2_SURFACE
00068 
00069 /* cairo_os2_surface_create() :                                   */
00070 /*                                                                */
00071 /* Create a Cairo surface which is bounded to a given presentation*/
00072 /* space (HPS). The surface will be created to have the given     */
00073 /* size.                                                          */
00074 /* By default: Every change to the surface will be made visible   */
00075 /*             immediately by blitting it into the window. This   */
00076 /*             can be changed with the                            */
00077 /*             cairo_os2_surface_set_blit_as_changes() API.       */
00078 /* Note that the surface will contain garbage when created, so the*/
00079 /* pixels have to be initialized by hand first. You can use the   */
00080 /* Cairo functions to fill it with black, or use the              */
00081 /* cairo_surface_mark_dirty() API to fill the surface with pixels */
00082 /* from the window/HPS.                                           */
00083 
00084 cairo_surface_t *
00085 cairo_os2_surface_create (HPS hpsClientWindow,
00086                           int iWidth, int iHeight);
00087 
00088 /* cairo_os2_surface_set_HWND() :                                 */
00089 /*                                                                */
00090 /* Sets window handle for surface. If Cairo wants to blit into the*/
00091 /* window because it's set that it should blit as the surface     */
00092 /* changes (see cairo_os2_surface_set_blit_as_changes() API), then*/
00093 /* there are two ways it can choose:                              */
00094 /* If it knows the HWND of the surface, then it invalidates that  */
00095 /* area, so the application will get a WM_PAINT message and it can*/
00096 /* call cairo_os2_surface_repaint_window() to redraw that area.   */
00097 /* Otherwise cairo itself will use the HPS it got at surface      */
00098 /* creation time, and blit the pixels itself.                     */
00099 /* It's also a solution, but experience shows that if this happens*/
00100 /* from a non-PM thread, then it can screw up PM internals.       */
00101 /*                                                                */
00102 /* So, best solution is to set the HWND for the surface after the */
00103 /* surface creation, so every blit will be done from application's*/
00104 /* message processing loop, which is the safest way to do.        */
00105 
00106 void
00107 cairo_os2_surface_set_HWND (cairo_surface_t *pSurface,
00108                             HWND hwndClientWindow);
00109 
00110 /* cairo_os2_surface_set_blit_as_changes() :                      */
00111 /*                                                                */
00112 /* This API can tell Cairo if it should show every change to this */
00113 /* surface immediately in the window, or if it should be cached   */
00114 /* and will only be visible if the user calls the                 */
00115 /* cairo_os2_surface_repaint_window() API explicitly.             */
00116 /* If the HWND was not told to Cairo, then it will use the HPS to */
00117 /* blit the graphics. Otherwise it will invalidate the given      */
00118 /* window region so the user will get WM_PAINT to redraw that area*/
00119 /* of the window.                                                 */
00120 
00121 void
00122 cairo_os2_surface_set_blit_as_changes (cairo_surface_t *pSurface,
00123                                        int bBlitAsChanges);
00124 
00125 /* cairo_os2_surface_get_blit_as_changes() :                      */
00126 /*                                                                */
00127 /* This API can return the current mode of the surface. It is     */
00128 /* TRUE by default.                                               */
00129 
00130 int
00131 cairo_os2_surface_get_blit_as_changes (cairo_surface_t *pSurface);
00132 
00133 /* cairo_os2_surface_window_resized() :                           */
00134 /*                                                                */
00135 /* When the client window is resized, call this API so the        */
00136 /* underlaying surface will also be resized. This function will   */
00137 /* reallocate everything, so you'll have to redraw everything in  */
00138 /* the surface after this call.                                   */
00139 /* The surface will contain garbage after the resizing, just like */
00140 /* after cairo_os2_surface_create(), so all those notes also apply*/
00141 /* here, please read that!                                        */
00142 /*                                                                */
00143 /* The timeout value is in milliseconds, and tells how much the   */
00144 /* function should wait on other parts of the program to release  */
00145 /* the buffers. It is necessary, because it can be that Cairo is  */
00146 /* just drawing something into the surface while we want to       */
00147 /* destroy and recreate it.                                       */
00148 /* Returns CAIRO_STATUS_SUCCESS if the surface could be resized,  */
00149 /* or returns other error code if                                 */
00150 /*  - the surface is not a real OS/2 Surface                      */
00151 /*  - there is not enough memory to resize the surface            */
00152 /*  - waiting for all the buffers to be released timed out        */
00153 
00154 int
00155 cairo_os2_surface_window_resized (cairo_surface_t *pSurface,
00156                                   int iNewWidth, int iNewHeight,
00157                                   int iTimeOut);
00158 
00159 /* cairo_os2_surface_repaint_window() :                           */
00160 /*                                                                */
00161 /* This function can be used to force a repaint of a given area   */
00162 /* of the client window. Most of the time it is called from the   */
00163 /* WM_PAINT processing of the window proc. However, it can be     */
00164 /* called anytime if a given part of the window has to be updated.*/
00165 /*                                                                */
00166 /* The function expects a HPS of the window, and a RECTL to tell  */
00167 /* which part of the window should be redrawn.                    */
00168 /* The returned values of WinBeginPaint() is just perfect here,   */
00169 /* but you can also get the HPS by using the WinGetPS() function, */
00170 /* and you can assemble your own update rect by hand.             */
00171 /* If the hpsBeginPaint parameter is NULL, the function will use  */
00172 /* the HPS you passed in to cairo_os2_surface_create(). If the    */
00173 /* prclBeginPaintRect parameter is NULL, the function will query  */
00174 /* the current window size and repaint the whole window.          */
00175 /*                                                                */
00176 /* Cairo/2 assumes that if you told the HWND to the surface using */
00177 /* the cairo_os2_surface_set_HWND() API, then this function will  */
00178 /* be called by the application every time it gets a WM_PAINT for */
00179 /* that HWND. If the HWND is told to the surface, Cairo uses this */
00180 /* function to handle dirty areas too, so you were warned. :)     */
00181 
00182 void
00183 cairo_os2_surface_repaint_window (cairo_surface_t *pSurface,
00184                                   HPS hpsBeginPaint,
00185                                   PRECTL prclBeginPaintRect);
00186 
00187 #endif /* CAIRO_HAS_OS2_SURFACE */
00188 
00189 CAIRO_END_DECLS
00190 
00191 #endif /* _CAIRO_OS2_H_ */