Convert ddraw.txt to ddraw.sgml and add it to the wine-devel
documentation.
This commit is contained in:
Chris Morgan
Alexandre Julliard
parent
a56d40f490
commit
5a6d23179a
|
|
@ -27,6 +27,7 @@ WINE_DEVEL_SRCS = \
|
||||||
architecture.sgml \
|
architecture.sgml \
|
||||||
consoles.sgml \
|
consoles.sgml \
|
||||||
cvs-regression.sgml \
|
cvs-regression.sgml \
|
||||||
|
ddraw.sgml \
|
||||||
debugger.sgml \
|
debugger.sgml \
|
||||||
debugging.sgml \
|
debugging.sgml \
|
||||||
documentation.sgml \
|
documentation.sgml \
|
||||||
|
|
|
||||||
|
|
@ -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:
|
||||||
|
-->
|
||||||
|
|
@ -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.
|
|
||||||
|
|
@ -10,6 +10,7 @@
|
||||||
<!entity debugging SYSTEM "debugging.sgml">
|
<!entity debugging SYSTEM "debugging.sgml">
|
||||||
<!entity ole SYSTEM "ole.sgml">
|
<!entity ole SYSTEM "ole.sgml">
|
||||||
<!entity opengl SYSTEM "opengl.sgml">
|
<!entity opengl SYSTEM "opengl.sgml">
|
||||||
|
<!entity ddraw SYSTEM "ddraw.sgml">
|
||||||
<!entity multimedia SYSTEM "multimedia.sgml">
|
<!entity multimedia SYSTEM "multimedia.sgml">
|
||||||
|
|
||||||
<!entity implementation SYSTEM "implementation.sgml">
|
<!entity implementation SYSTEM "implementation.sgml">
|
||||||
|
|
@ -122,6 +123,7 @@
|
||||||
&debugging;
|
&debugging;
|
||||||
&ole;
|
&ole;
|
||||||
&opengl;
|
&opengl;
|
||||||
|
&ddraw;
|
||||||
&multimedia;
|
&multimedia;
|
||||||
</part>
|
</part>
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue