ReceiveTempSMS
/
Sweden-Number
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Convert ddraw.txt to ddraw.sgml and add it to the wine-devel 

documentation.
This commit is contained in:
Chris Morgan 2004-03-20 19:23:56 +00:00 committed by Alexandre Julliard
parent a56d40f490
commit 5a6d23179a
4 changed files with 175 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
documentation/Makefile.in
View File

@ -27,6 +27,7 @@ WINE_DEVEL_SRCS = \
architecture.sgml \
consoles.sgml \
cvs-regression.sgml \
ddraw.sgml \
debugger.sgml \
debugging.sgml \
documentation.sgml \

172
documentation/ddraw.sgml Normal file
View File

@ -0,0 +1,172 @@
<chapter id="ddraw">
<title>Outline of DirectDraw Architecture</title>
<para>
This is an outline of the architecture. Many details are
skipped, but hopefully this is useful.
</para>
<sect1 id="ddinheritance">
<title>DirectDraw inheritance tree</title>
<programlisting>
Main
|
User
|-----------\
XVidMode DGA2
</programlisting>
<para>
Most of the DirectDraw functionality is implemented in a common base
class. Derived classes are responsible for providing display
mode functions (Enum, Set, Restore), GetCaps, GetDevice identifier
and internal functions called to create primary and backbuffer
surfaces.
</para>
<para>
User provides for DirectDraw capabilities based on drawing to a
Wine window. It uses the User DirectDrawSurface implementation
for primary and backbuffer surfaces.
<para>
XVidMode attempt to use the XFree86 VidMode extension to set the
display resolution to match the parameters to SetDisplayMode.
</para>
<para>
DGA2 attempt to use the XFree86 DGA 2.x extension to set the
display resolution and direct access to the framebuffer, if the
full-screen-exclusive cooperative level is used. If not, it just
uses the User implementation.
</para>
</sect1>
<sect1 id="ddsurfaceinheritance">
<title>DirectDrawSurface inheritance tree</title>
<programlisting>
Main
|--------------\
| |
DIB Fake Z-Buffer
|
|------\---------\
| | |
User DGA2 DIBTexture
</programlisting>
<para>
Main provides a very simple base class that does not implement any of
the image-related functions. Therefore it does not place any
constraints on how the surface data is stored.
</para>
<para>
DIB stores the surface data in a DIB section. It is used by the Main
DirectDraw driver to create off-screen surfaces.
</para>
<para>
User implements primary and backbuffer surfaces for the User DirectDraw
driver. If it is a primary surface, it will attempt to keep itself
synchronized to the window.
</para>
<para>
DGA2 surfaces claims an appropriate section of framebuffer space and
lets DIB build its DIB section on top of it.
</para>
<para>
Fake Z-Buffer surfaces are used by Direct3D to indicate that a primary
surface has an associated z-buffer. For a first implementation, it
doesn't need to store any image data since it is just a placeholder.
</para>
<para>
(Actually 3D programs will rarely use Lock or GetDC on primary
surfaces, backbuffers or z-buffers so we may want to arrange for
lazy allocation of the DIB sections.)
</para>
</sect1>
<sect1 id="interfacethunks">
<title>Interface Thunks</title>
<para>
Only the most recent version of an interface needs to be implemented.
Other versions are handled by having thunks convert their parameters
and call the root version.
</para>
<para>
Not all interface versions have thunks. Some versions could be combined
because their parameters were compatible. For example if a structure
changes but the structure has a dwSize field, methods using that structure
are compatible, as long as the implementation remembers to take the dwSize
into account.
</para>
<para>
Interface thunks for Direct3D are more complicated since the paradigm
changed between versions.
</para>
</sect1>
<sect1 id="logicalobjectlayout">
<title>Logical Object Layout</title>
<para>
The objects are split into the generic part (essentially the fields for
Main) and a private part. This is necessary because some objects
can be created with CoCreateInstance, then Initialized later. Only
at initialization time do we know which class to use. Each class
except Main declares a Part structure and adds that to its Impl.
</para>
<para>
For example, the DIBTexture DirectDrawSurface implementation looks
like this:
</para>
<programlisting>
struct DIBTexture_DirectDrawSurfaceImpl_Part
{
union DIBTexture_data data; /*declared in the real header*/
};
typedef struct
{
struct DIB_DirectDrawSurfaceImpl_Part dib;
struct DIBTexture_DirectDrawSurfaceImpl_Part dibtexture;
} DIBTexture_DirectDrawSurfaceImpl;
</programlisting>
<para>
So the DIBTexture surface class is derived from the DIB surface
class and it adds one piece of data, a union.
</para>
<para>
Main does not have a Part structure. Its fields are stored in
IDirectDrawImpl/IDirectDrawSurfaceImpl.
</para>
<para>
To access private data, one says
</para>
<programlisting>
DIBTexture_DirectDrawSurfaceImpl* priv = This->private;
do_something_with(priv->dibtexture.data);
</programlisting>
</sect1>
<sect1 id="creatingobject">
<title>Creating Objects</title>
<para>
Classes have two functions relevant to object creation, Create and
Construct. To create a new object, the class' Create function is
called. It allocates enough memory for IDirectDrawImpl or
IDirectDrawSurfaceImpl as well as the private data for derived
classes and then calls Construct.
</para>
<para>
Each class's Construct function calls the base class's Construct,
then does the necessary initialization.
</para>
<para>
For example, creating a primary surface with the user ddraw driver
calls User_DirectDrawSurface_Create which allocates memory for the
object and calls User_DirectDrawSurface_Construct to initialize it.
This calls DIB_DirectDrawSurface_Construct which calls
Main_DirectDrawSurface_Construct.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-devel.sgml" "set" "book" "chapter" "")
End:
-->

134
documentation/ddraw.txt
View File

@ -1,134 +0,0 @@
This is an outline of the architecture. Many details are
skipped, but hopefully this is useful.
By Andrew Lewycky <andrew@transgaming.com>
(with updates by Ove Kåven <ovek@transgaming.com>)
* DirectDraw inheritance tree
Main
|
User
|-----------\
XVidMode DGA2
Most of the DirectDraw functionality is implemented in a common base
class. Derived classes are responsible for providing display
mode functions (Enum, Set, Restore), GetCaps, GetDevice identifier
and internal functions called to create primary and backbuffer
surfaces.
User provides for DirectDraw capabilities based on drawing to a
Wine window. It uses the User DirectDrawSurface implementation
for primary and backbuffer surfaces.
XVidMode attempt to use the XFree86 VidMode extension to set the
display resolution to match the parameters to SetDisplayMode.
DGA2 attempt to use the XFree86 DGA 2.x extension to set the
display resolution and direct access to the framebuffer, if the
full-screen-exclusive cooperative level is used. If not, it just
uses the User implementation.
* DirectDrawSurface inheritance tree
Main
|--------------\
| |
DIB Fake Z-Buffer
|
|------\---------\
| | |
User DGA2 DIBTexture
Main provides a very simple base class that does not implement any of
the image-related functions. Therefore it does not place any
constraints on how the surface data is stored.
DIB stores the surface data in a DIB section. It is used by the Main
DirectDraw driver to create off-screen surfaces.
User implements primary and backbuffer surfaces for the User DirectDraw
driver. If it is a primary surface, it will attempt to keep itself
synchronized to the window.
DGA2 surfaces claims an appropriate section of framebuffer space and
lets DIB build its DIB section on top of it.
Fake Z-Buffer surfaces are used by Direct3D to indicate that a primary
surface has an associated z-buffer. For a first implementation, it
doesn't need to store any image data since it is just a placeholder.
(Actually 3D programs will rarely use Lock or GetDC on primary
surfaces, backbuffers or z-buffers so we may want to arrange for
lazy allocation of the DIB sections.)
* Interface Thunks
Only the most recent version of an interface needs to be implemented.
Other versions are handled by having thunks convert their parameters
and call the root version.
Not all interface versions have thunks. Some versions could be combined
because their parameters were compatible. For example if a structure
changes but the structure has a dwSize field, methods using that structure
are compatible, as long as the implementation remembers to take the dwSize
into account.
Interface thunks for Direct3D are more complicated since the paradigm
changed between versions.
* Logical Object Layout
The objects are split into the generic part (essentially the fields for
Main) and a private part. This is necessary because some objects
can be created with CoCreateInstance, then Initialized later. Only
at initialisation time do we know which class to use. Each class
except Main declares a Part structure and adds that to its Impl.
For example, the DIBTexture DirectDrawSurface implementation looks
like this:
struct DIBTexture_DirectDrawSurfaceImpl_Part
{
union DIBTexture_data data; /*declared in the real header*/
};
typedef struct
{
struct DIB_DirectDrawSurfaceImpl_Part dib;
struct DIBTexture_DirectDrawSurfaceImpl_Part dibtexture;
} DIBTexture_DirectDrawSurfaceImpl;
So the DIBTexture surface class is derived from the DIB surface
class and it adds one piece of data, a union.
Main does not have a Part structure. Its fields are stored in
IDirectDrawImpl/IDirectDrawSurfaceImpl.
To access private data, one says
DIBTexture_DirectDrawSurfaceImpl* priv = This->private;
do_something_with(priv->dibtexture.data);
* Creating Objects
Classes have two functions relevant to object creation, Create and
Construct. To create a new object, the class' Create function is
called. It allocates enough memory for IDirectDrawImpl or
IDirectDrawSurfaceImpl as well as the private data for derived
classes and then calls Construct.
Each class's Construct function calls the base class's Construct,
then does the necessary initialization.
For example, creating a primary surface with the user ddraw driver
calls User_DirectDrawSurface_Create which allocates memory for the
object and calls User_DirectDrawSurface_Construct to initialize it.
This calls DIB_DirectDrawSurface_Construct which calls
Main_DirectDrawSurface_Construct.

2
documentation/wine-devel.sgml
View File

@ -10,6 +10,7 @@
<!entity debugging SYSTEM "debugging.sgml">
<!entity ole SYSTEM "ole.sgml">
<!entity opengl SYSTEM "opengl.sgml">
<!entity ddraw SYSTEM "ddraw.sgml">
<!entity multimedia SYSTEM "multimedia.sgml">
<!entity implementation SYSTEM "implementation.sgml">
@ -122,6 +123,7 @@
&debugging;
&ole;
&opengl;
&ddraw;
&multimedia;
</part>