summaryrefslogtreecommitdiffstats
path: root/dxsdk/Include/d3dxsprite.h
blob: a08b4a99c134324db98ce8a4c243ab44c3aae6f7 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
///////////////////////////////////////////////////////////////////////////
//
//  Copyright (C) Microsoft Corporation.  All Rights Reserved.
//
//  File:       d3dxsprite.h
//  Content:    D3DX sprite helper functions
//
//      These functions allow you to use sprites with D3DX. A "sprite" is
//      loosely defined as a 2D image that you want to transfer to the 
//      rendering target. The source image can be a texture created
//      with the help of the D3DX texture loader; though advanced users may
//      want to create their own. A helper function (PrepareDeviceForSprite)
//      is provided to make it easy to set up render states on a device. 
//      (Again, advanced users can use their own created devices.) 
//
//      There are two general techniques for sprites; the simpler one just
//      specifies a destination rectangle and a rotation anlge. A more 
//      powerful technique supports rendering to non-rectangular quads.
//
//      Both techniques support clipping, alpha, and rotation. More
//      details are below.
//
///////////////////////////////////////////////////////////////////////////

#ifndef __D3DXSPRITE_H__
#define __D3DXSPRITE_H__

#include <d3d.h>
#include <limits.h>
#include "d3dxerr.h"

#ifdef __cplusplus
extern "C" {
#endif


//-------------------------------------------------------------------------
// D3DXPrepareDeviceForSprite:
//
// Call this function to set up all the render states necessary for
// BltSprite/WarpSprite to work correctly. (Advanced users may opt to
// not call this function first; in which case Blt/WarpSprite functions
// will use whatever render/texture states were set up on the device when
// they are called.)
//
// Warning: This function modifies render states and may impact performance
// negatively on some 3D hardware if it is called too often per frame.
//
// Warning: If the render state changes (other than through calls to 
// BltSprite or WarpSprite), you will need to call this function again before 
// calling BltSprite or WarpSprite.
//
// Details: This function modifies the the rendering first texture stage and 
// it modifies some renderstates for the entire device. Here is the exact 
// list:
// 
//   SetTextureStageState(0, D3DTSS_COLORARG1,         D3DTA_TEXTURE);
//   SetTextureStageState(0, D3DTSS_COLOROP,           D3DTOP_SELECTARG1);
//   SetTextureStageState(0, D3DTSS_ALPHAARG1,         D3DTA_TEXTURE);
//   SetTextureStageState(0, D3DTSS_ALPHAARG2,         D3DTA_DIFFUSE);
//   SetTextureStageState(0, D3DTSS_ALPHAOP,           D3DTOP_MODULATE);
//   SetTextureStageState(0, D3DTSS_MINFILTER,         D3DTFN_LINEAR);
//   SetTextureStageState(0, D3DTSS_MAGFILTER,         D3DTFG_LINEAR);
// 
//   SetRenderState(D3DRENDERSTATE_SRCBLEND,           D3DBLEND_SRCALPHA);
//   SetRenderState(D3DRENDERSTATE_DESTBLEND,          D3DBLEND_INVSRCALPHA);
//   SetRenderState(D3DRENDERSTATE_ALPHABLENDENABLE,   TRUE);
//
//   Depending on the value of ZEnable parameter, this function will
//   will either call
//   SetRenderState(D3DRENDERSTATE_ZENABLE,            FALSE);
//   - or -
//   SetRenderState(D3DRENDERSTATE_ZENABLE,            TRUE);
//
// Parameters: 
//      pd3dDevice  - a pointer to the d3d device that you wish to prepare
//                    for use with D3DX Sprite Services
//      ZEnable     - a flag indicating whether you want the sprites to
//                    check and update the Z buffer as part of rendering.
//                    If ZEnable is FALSE, OR you are using
//                    alpha-blending, then it is necessary to render your
//                    sprites from back-to-front. 
//
//-------------------------------------------------------------------------

#ifdef __cplusplus
HRESULT WINAPI
    D3DXPrepareDeviceForSprite( LPDIRECT3DDEVICE7 pd3dDevice, 
                                BOOL ZEnable = FALSE);
#else
HRESULT WINAPI
    D3DXPrepareDeviceForSprite( LPDIRECT3DDEVICE7 pd3dDevice, 
                                BOOL ZEnable);
#endif



//-------------------------------------------------------------------------
// The D3DXDrawBasicSprite() function performs blitting of source images onto 
// a 3D rendering device. This function only calls SetTexture on the first 
// renderstage with the parameter (pd3dTexture) if that parameter is non-null. 
// This function assumes that D3DXPrepareDeviceForSprite has been called on 
// the device or that caller has in some other way correctly prepared the 
// renderstates.
//
// This function supports scaling, rotations, alpha-blending, and choosing 
// a source sub-rect.
// 
// Rotation angle is specified in radians. Both rotations and scales
// are applied around the center of the sprite; where the center of the
// sprite is half the width/height of the sprite, plus the offset parameter. 
//
// Use the offset parameter if you want the sprite's center to be something 
// other than the image center.
//
// The destination point indicates where you would like the center of
// the sprite to draw to.
//
// Parameters: 
//      pd3dTexture - a pointer to the surface containing the texture
//      pd3dDevice  - a pointer to the d3d device to render to. It is
//                    assumed that render states are set up. (See
//                    D3DXPrepareDeviceForSprite)
//      ppointDest  - a pointer to the target point for the sprite. The
//                    components of the vector must be in screen
//                    space.
//      alpha       - alpha value to apply to sprite. 1.0 means totally
//                    opaque; and 0.0 means totally transparent. 
//                    WARNING: If you are using alpha, then you should render
//                    from back to front in order to avoid rendering
//                    artifacts.
//      angleRad    - angle of rotation around the 'center' of the rect
//      scale       - a uniform scale that is applied to the source rect
//                    to specify the size of the image that is rendered
//      pOffset     - offset from the center of the source rect to use as the 
//                    center of rotation
//      pSourceRect - a rect that indicates what portion of the source
//                    source texture to use. If NULL is passed, then the
//                    entire source is used. If the source texture was 
//                    created via D3DX, then the rect should be specified
//                    in the coordinates of the original image (so that you
//                    don't have to worry about stretching/scaling that D3DX
//                    may have done to make the image work with your current
//                    3D Device.) Note that horizontal or vertical mirroring 
//                    may be simply accomplished by swapping the left/right 
//                    or top/bottom fields of this RECT.
//-------------------------------------------------------------------------

#ifdef __cplusplus
HRESULT WINAPI 
    D3DXDrawSpriteSimple(LPDIRECTDRAWSURFACE7  pd3dTexture, 
                         LPDIRECT3DDEVICE7     pd3dDevice, 
                         const D3DXVECTOR3     *ppointDest, 
                         float                 alpha        = 1.0f,
                         float                 scale        = 1.0f,
                         float                 angleRad     = 0.0f,
                         const D3DXVECTOR2     *pOffset     = NULL,
                         const RECT            *pSourceRect = NULL);
#else
HRESULT WINAPI 
    D3DXDrawSpriteSimple(LPDIRECTDRAWSURFACE7  pd3dTexture, 
                         LPDIRECT3DDEVICE7     pd3dDevice, 
                         D3DXVECTOR3           *ppointDest, 
                         float                 alpha,
                         float                 scale,
                         float                 angleRad,
                         D3DXVECTOR2           *pOffset,
                         RECT                  *pSourceRect);
#endif

//-------------------------------------------------------------------------
// The D3DXDrawSprite() function transforms source images onto a 3D 
// rendering device. It takes a general 4x4 matrix which is use to transform
// the points of a default rect: (left=-.5, top=-.5, right=+.5, bottom=+.5).
// (This default rect was chosen so that it was centered around the origin
// to ease setting up rotations. And it was chosen to have a width/height of one
// to ease setting up scales.)
// 
// This function only calls SetTexture on the first 
// renderstage with the parameter (pd3dTexture) if that parameter is non-null. 
// This function assumes that D3DXPrepareDeviceForSprite has been called on 
// the device or that caller has in some other way correctly prepared the 
// renderstates.
//
// This function supports alpha-blending, and choosing 
// a source sub-rect. (A value of NULL for source sub-rect means the entire
// texture is used.)
//
// Note that if the transformed points have a value for w (the homogenous
// coordinate) that is not 1, then this function will invert it and pass
// that value to D3D as the rhw field of a TLVERTEX. If the value for w is
// zero, then it use 1 as the rhw.
//
// Parameters: 
//      pd3dTexture - a pointer to the surface containing the texture
//      pd3dDevice  - a pointer to the d3d device to render to. It is
//                    assumed that render states are set up. (See
//                    D3DXPrepareDeviceForSprite)
//      pMatrixTransform - 4x4 matrix that specifies the transformation
//                    that will be applied to the default -.5 to +.5 
//                    rectangle.
//      alpha       - alpha value to apply to sprite. 1.0 means totally
//                    opaque; and 0.0 means totally transparent. 
//                    WARNING: If you are using alpha, then you should render
//                    from back to front in order to avoid rendering
//                    artifacts.Furthermore, you should avoid scenarios where 
//                    semi-transparent objects intersect.
//      pSourceRect - a rect that indicates what portion of the source
//                    source texture to use. If NULL is passed, then the
//                    entire source is used. If the source texture was 
//                    created via D3DX, then the rect should be specified
//                    in the coordinates of the original image (so that you
//                    don't have to worry about stretching/scaling that D3DX
//                    may have done to make the image work with your current
//                    3D Device.) Note that mirroring may be simply accomplished
//                    by swapping the left/right or top/bottom fields of
//                    this RECT.
// 
//-------------------------------------------------------------------------

#ifdef __cplusplus
HRESULT WINAPI 
    D3DXDrawSpriteTransform(LPDIRECTDRAWSURFACE7  pd3dTexture, 
                            LPDIRECT3DDEVICE7     pd3dDevice, 
                            const D3DXMATRIX      *pMatrixTransform, 
                            float                 alpha         = 1.0f,
                            const RECT            *pSourceRect  = NULL);
#else
HRESULT WINAPI 
    D3DXDrawSpriteTransform(LPDIRECTDRAWSURFACE7  pd3dTexture, 
                            LPDIRECT3DDEVICE7     pd3dDevice, 
                            D3DXMATRIX            *pMatrixTransform, 
                            float                 alpha,
                            RECT                  *pSourceRect);
#endif

//-------------------------------------------------------------------------
// The D3DXBuildSpriteTransform() function is a helper provided which
// creates a matrix corresponding to simple properties. This matrix is
// set up to pass directly to D3DXTransformSprite.
//
// Parameters: 
//      pMatrix     - a pointer to the result matrix
//      prectDest   - a pointer to the target rectangle for the sprite
//      angleRad    - angle of rotation around the 'center' of the rect
//      pOffset     - offset from the center of the source rect to use as the 
//                    center of rotation
// 
//-------------------------------------------------------------------------

#ifdef __cplusplus
void WINAPI
    D3DXBuildSpriteTransform(D3DXMATRIX            *pMatrix,
                             const RECT            *prectDest,
                             float                 angleRad     = 0.0f,
                             const D3DXVECTOR2     *pOffset     = NULL);
#else
void WINAPI
    D3DXBuildSpriteTransform(D3DXMATRIX            *pMatrix,
                             RECT                  *prectDest,
                             float                 angleRad,
                             D3DXVECTOR2           *pOffset);
#endif


//-------------------------------------------------------------------------
// The D3DXDrawSprite3D() function renders a texture onto a 3D quad. The
// quad ABCD is broken into two triangles ABC and ACD which are rendered
// via DrawPrim.
//
// Parameters: 
//      pd3dTexture - a pointer to the surface containing the texture
//      pd3dDevice  - a pointer to the d3d device to render to. It is
//                    assumed that render states are set up. (See
//                    D3DXPrepareDeviceForSprite)
//      quad        - array of 4 points in the following order:
//                    upper-left, upper-right, lower-right, lower-left.
//                    If these vectors contain a W, then this function
//                    will take the reciprocal of that value to pass as
//                    as the rhw (i.e. reciprocal homogenous w).
//      alpha       - alpha value to apply to sprite. 1.0 means totally
//                    opaque; and 0.0 means totally transparent. 
//                    WARNING: If you are using alpha, then you should render
//                    from back to front in order to avoid rendering
//                    artifacts.Furthermore, you should avoid scenarios where 
//                    semi-transparent objects intersect.
//      pSourceRect - a rect that indicates what portion of the source
//                    source texture to use. If NULL is passed, then the
//                    entire source is used. If the source texture was 
//                    created via D3DX, then the rect should be specified
//                    in the coordinates of the original image (so that you
//                    don't have to worry about stretching/scaling that D3DX
//                    may have done to make the image work with your current
//                    3D Device.) Note that mirroring may be simply accomplished
//                    by swapping the left/right or top/bottom fields of
//                    this RECT.
//-------------------------------------------------------------------------

#ifdef __cplusplus
HRESULT WINAPI 
    D3DXDrawSprite3D(LPDIRECTDRAWSURFACE7  pd3dTexture, 
                     LPDIRECT3DDEVICE7     pd3dDevice, 
                     const D3DXVECTOR4     quad[4], 
                     float                 alpha         = 1.0f,
                     const RECT            *pSourceRect  = NULL);
#else
HRESULT WINAPI 
    D3DXDrawSprite3D(LPDIRECTDRAWSURFACE7  pd3dTexture, 
                     LPDIRECT3DDEVICE7     pd3dDevice, 
                     D3DXVECTOR4           quad[4], 
                     float                 alpha,
                     RECT                  *pSourceRect);
#endif



#ifdef __cplusplus
} // extern "C"
#endif

#endif // __D3DXSPRITE_H__