← Back to branch summary

~drgeo-developers/drgeo/trunk

« back to all changes in this revision

Viewing changes to VMs/iPad/source/Cross/plugins/SurfacePlugin/SurfacePlugin.h

  • Committer: Hilaire Fernandes
  • Date: 2012-01-27 21:15:40 UTC
  • Revision ID: hilaire.fernandes@gmail.com-20120127211540-912spf97bhpx6mve
Initial additions

Show diffs side-by-side

added added

removed removed

Lines of Context:
VMs/iPad/source/Cross/plugins/SurfacePlugin/SurfacePlugin.h
 
1
#ifndef __SQ_DRAW_SURFACE_H
 
2
#define __SQ_DRAW_SURFACE_H
 
3
/* v1.0 */
 
4
#define SQ_SURFACE_MAJOR 1
 
5
#define SQ_SURFACE_MINOR 0
 
6
 
 
7
/* Plugins creating their own surfaces must register these using
 
8
   the following set of functions. The typedefs are for easier casts. */
 
9
typedef int (*fn_getSurfaceFormat)(int surfaceHandle, int* width, int* height, int* depth, int* isMSB);
 
10
typedef int (*fn_lockSurface)(int surfaceHandle, int *pitch, int x, int y, int w, int h);
 
11
typedef int (*fn_unlockSurface)(int surfaceHandle, int x, int y, int w, int h);
 
12
typedef int (*fn_showSurface)(int surfaceHandle, int x, int y, int w, int h);
 
13
 
 
14
typedef struct sqSurfaceDispatch {
 
15
        /* Version information. Must be provided by the client
 
16
           so the surface manager can check if certain operations
 
17
           are supported. */
 
18
        int majorVersion;
 
19
        int minorVersion;
 
20
 
 
21
        /* Version 1.0 */
 
22
        fn_getSurfaceFormat getSurfaceFormat;
 
23
        fn_lockSurface lockSurface;
 
24
        fn_unlockSurface unlockSurface;
 
25
        fn_showSurface showSurface;
 
26
} sqSurfaceDispatch;
 
27
 
 
28
/* The functions for sqSurfaceDispatch are:
 
29
 
 
30
        int getSurfaceFormat(int handle, int* width, int* height, int* depth, int* isMSB);
 
31
                Return general information about the OS drawing surface.
 
32
                Return true if successful, false otherwise.
 
33
 
 
34
                The returned values describe the basic properties such as
 
35
                width, height, depth and LSB vs. MSB pixels.
 
36
 
 
37
        int lockSurface(int handle, int *pitch, int x, int y, int w, int h);
 
38
                Lock the bits of the surface.
 
39
                Return a pointer to the actual surface bits, or NULL on failure.
 
40
                If successful, store the pitch of the surface (e.g., the bytes
 
41
                per scan line).
 
42
 
 
43
                For equal source/dest handles only one locking operation is performed.
 
44
                This is to prevent locking of overlapping areas which does not work with
 
45
                certain APIs (e.g., DirectDraw prevents locking of overlapping areas). 
 
46
                A special case for non-overlapping but equal source/dest handle would 
 
47
                be possible but we would have to transfer this information over to 
 
48
                unlockSurfaces somehow (currently, only one unlock operation is 
 
49
                performed for equal source and dest handles). Also, this would require
 
50
                a change in the notion of ioLockSurface() which is right now interpreted
 
51
                as a hint and not as a requirement to lock only the specific portion of
 
52
                the surface.
 
53
 
 
54
                The arguments in ioLockSurface() provide the implementation with
 
55
                an explicit hint what area is affected. It can be very useful to
 
56
                know the max. affected area beforehand if getting the bits requires expensive
 
57
                copy operations (e.g., like a roundtrip to the X server or a glReadPixel op).
 
58
                However, the returned pointer *MUST* point to the virtual origin of the surface
 
59
                and not to the beginning of the rectangle. The promise made by BitBlt
 
60
                is to never access data outside the given rectangle (aligned to 4byte boundaries!)
 
61
                so it is okay to return a pointer to the virtual origin that is actually outside
 
62
                the valid memory area.
 
63
 
 
64
                The area provided in ioLockSurface() is already clipped (e.g., it will always
 
65
                be inside the source and dest boundingBox) but it is not aligned to word boundaries
 
66
                yet. It is up to the support code to compute accurate alignment if necessary.
 
67
 
 
68
        int unlockSurface(int handle, int x, int y, int w, int h);
 
69
                Unlock the bits of a (possibly modified) surface after BitBlt completed.
 
70
                The return value is ignored.
 
71
 
 
72
                The arguments provided specify the dirty region of the surface. If the
 
73
                surface is unmodified all arguments are set to zero.
 
74
 
 
75
        int showSurface(int handle, int x, int y, int w, int h);
 
76
                Display the contents of the surface on the actual screen.
 
77
 
 
78
                If ioShowSurface() is called the surface in question represents
 
79
                a Squeak DisplayScreen.
 
80
 
 
81
        FXBlt uses a variant of the above functions which are exported from
 
82
        the surface plugin:
 
83
 
 
84
        int ioGetSurfaceFormat(int surfaceID, int* width, int* height, int* depth, int* isMSB);
 
85
        int ioLockSurface(int surfaceID, int *pitch, int x, int y, int w, int h);
 
86
        int ioUnlockSurface(int surfaceID, int x, int y, int w, int h);
 
87
 
 
88
        These functions are looked up in the registered surfaces and invoked
 
89
        as appropriate. The meaning of all values is exactly the same as for
 
90
        the functions specified in sqSurfaceDispatch with the exception that
 
91
        the surfaceID represents the 'bits' handle of the Form that is used
 
92
        within FXBlt.
 
93
 
 
94
        Interpreter itself uses a separate entry point for updating the display
 
95
 
 
96
        int ioShowSurface(int surfaceID, int x, int y, int w, int h);
 
97
 
 
98
        since the management of deferred updates is currently an intrinsic
 
99
        property of the VM (which is bad - deferred updates should be a
 
100
        property of the DisplayScreen in question and not of the VM but
 
101
        that's the way it is...).
 
102
 
 
103
*/
 
104
 
 
105
/* The following are the entry points for the surface manager:
 
106
 
 
107
        int ioRegisterSurface(int surfaceHandle, sqSurfaceDispatch *fn, int *surfaceID);
 
108
                Register a new surface with the given handle and
 
109
                the set of surface functions. The new ID is returned
 
110
                in surfaceID. Returns true if successful, false 
 
111
                otherwise.
 
112
 
 
113
        int ioUnregisterSurface(int surfaceID);
 
114
                Unregister the surface with the given handle.
 
115
                Returns true if successful, false otherwise.
 
116
 
 
117
        int ioFindSurface(int surfaceID, sqSurfaceDispatch *fn, int *surfaceHandle);
 
118
                Find the surface with the given ID, and, optionally,
 
119
                the given set of surface functions. The registered handle
 
120
                is returned in surfaceHandle. Return true if successful
 
121
                (e.g., the surface has been found), false otherwise.
 
122
 
 
123
        The above entry points can be looked up through the interpreter, e.g., using
 
124
                interpreterProxy->ioLoadFunctionFrom("ioRegisterSurface","SurfacePlugin");
 
125
        The typedefs below are for easier casts.
 
126
*/
 
127
typedef int (*fn_ioRegisterSurface)(int surfaceHandle, sqSurfaceDispatch *fn, int *surfaceID);
 
128
typedef int (*fn_ioUnregisterSurface)(int surfaceID);
 
129
typedef int (*fn_ioFindSurface)(int surfaceID, sqSurfaceDispatch *fn, int *surfaceHandle);
 
130
 
 
131
#endif /* __SQ_DRAW_SURFACE_H */