• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    NV_video_output
4
5Name Strings
6
7    WGL_NV_video_output
8
9Contact
10
11    Thomas True, Nvidia, ttrue@nvidia.com
12    Ian Williams, Nvidia, iwilliams@nvidia.com
13    Martin Schwarzer, Nvidia, mschwarzer@nvidia.com
14
15Status
16
17    Shipping since 2004 for NVIDIA Quadro SDI (Serial Digital Interface)
18
19Version
20
21    Last Modified Date: February 20, 2008
22
23Number
24
25    349
26
27Dependencies
28
29    OpenGL 1.1 is required.
30    WGL_ARB_extension_string is required.
31    WGL_ARB_pixel_format is required.
32    WGL_ARB_pbuffer is required.
33
34Overview
35
36    This extension permits a color and or depth buffer of a pbuffer to
37    be used for rendering and subsequent video output.  After a pbuffer
38    has been bound to a video device, subsequent color and or depth
39    rendering into that buffer is displayed on the video output.
40
41Issues
42
43 1. Should the new pbuffer attributes be available through GL queries?
44
45    No, like other pbuffer attributes you need to query them through the
46    window system extension. This extension does not make any changes to
47    OpenGL.
48
49Implementation Notes
50
51 1. Any created pbuffers must be the same resolution as that specified
52    by the state of the video output device.
53
54 2. Applications may use a single pbuffer or a collection of pbuffers
55    to send frames/fields to a video device.  In the first case, an
56    application should block on the call to wglSendPbufferToVideoNV()
57    to ensure synchronization.  In the second caes, an application
58    should utilize wglGetVideoInfoNV() in order to query vblank and
59    buffer counters for synchronization.
60
61Intended Usage
62
63    1) Configure the video output device via the NVCPL API or via
64       the control panel which uses the NVCPL API.
65
66    2) Call wglChoosePixelFormatARB and find a suitable pixel format
67       for rendering images.  WGL_DRAW_TO_PBUFFER and one of
68       WGL_BIND_TO_VIDEO_RGB_NV, WGL_BIND_TO_VIDEO_RGBA_NV or
69       WGL_BIND_TO_VIDEO_RGB_AND_DEPTH_NV must be TRUE.  The
70       per-component pixel depth of the pbuffer must be equal to or
71       greater than the per-component depth of the video output.
72
73    3) Create pbuffers and associated rendering contexts for each
74       channel of video by calling wglCreatePbufferARB with one
75       of WGL_BIND_TO_VIDEO_RGB_NV, WGL_BIND_TO_VIDEO_RGBA_NV or
76       WGL_BIND_TO_VIDEO_RGB_AND_DEPTH_NV tokens in the attribute
77       list set to TRUE.  Set the width and height for each pbuffer
78       to match that of the intended video output device.
79
80    4) Call wglGetVideoDeviceNV to retrieve the handles for all
81       video devices available.  A video device handle is required
82       for each video stream.
83
84    5) Call wglBindVideoImageNV to bind each pbuffer drawable to a
85       corresponding video device handle.
86
87    6) Start transfers on each video device using the appropriate
88       NVCPL API function call.
89
90    7) Render the current frame/field for each stream to a
91       pbuffer. Once rendering is complete, call
92       wglSendPbufferToVideoNV() to send each frame/field to the video
93       device.
94
95    9) Render subsequent video frames or fields calling
96       wglSendPbufferToVideoNV() at the completion of rendering for
97       each frame/field.
98
99    10) Stop transfers on the video device via the appropriate NVCPL
100        API function call.
101
102    11) Call wglReleaseVideoImageNV to unbind each pbuffer drawable
103        from its associated video device.
104
105New Procedures and Functions
106
107    DECLARE_HANDLE(HPVIDEODEV);
108
109    BOOL wglGetVideoDeviceNV(HDC hDC, int numDevices,
110                             HPVIDEODEV *hVideoDevice);
111
112    BOOL wglReleaseVideoDeviceNV(HPVIDEODEV hVideoDevice);
113
114    BOOL wglBindVideoImageNV (HPVIDEODEV hVideoDevice,
115                              HPBUFFERARB hPbuffer, int iVideoBuffer);
116
117    BOOL wglReleaseVideoImageNV (HPBUFFERARB hPbuffer, int iVideoBuffer);
118
119    BOOL wglSendPbufferToVideoNV (HPBUFFERARB hPbuffer, int iBufferType,
120                                  unsigned long *pulCounterPbuffer,
121                                  BOOL bBlock);
122
123    BOOL wglGetVideoInfoNV (HPVIDEODEV hpVideoDevice,
124                            unsigned long *pulCounterOutputPbuffer,
125                            unsigned long *pulCounterOutputVideo);
126
127New Tokens
128
129    Accepted by the <piAttributes> parameter of wglGetPixelFormatAttribivARB,
130    wglGetPixelFormatAttribfvARB, and the <piAttribIList> and <pfAttribIList>
131    parameters of wglChoosePixelFormatARB and wglCreatePbufferARB:
132
133        WGL_BIND_TO_VIDEO_RGB_NV                        0x20C0
134        WGL_BIND_TO_VIDEO_RGBA_NV                       0x20C1
135        WGL_BIND_TO_VIDEO_RGB_AND_DEPTH_NV              0x20C2
136
137    Accepted by the <iVideoBuffer> parameter of wglBindVideoImageNV and
138    wglReleaseVideoImageNV:
139
140        WGL_VIDEO_OUT_COLOR_NV                          0x20C3
141        WGL_VIDEO_OUT_ALPHA_NV                          0x20C4
142        WGL_VIDEO_OUT_DEPTH_NV                          0x20C5
143        WGL_VIDEO_OUT_COLOR_AND_ALPHA_NV                0x20C6
144        WGL_VIDEO_OUT_COLOR_AND_DEPTH_NV                0x20C7
145
146    Accepted by the <iBufferType> parameter of wglSendPbufferToVideoNV:
147
148        WGL_VIDEO_OUT_FRAME                             0x20C8
149        WGL_VIDEO_OUT_FIELD_1                           0x20C9
150        WGL_VIDEO_OUT_FIELD_2                           0x20CA
151        WGL_VIDEO_OUT_STACKED_FIELDS_1_2                0x20CB
152        WGL_VIDEO_OUT_STACKED_FIELDS_2_1                0x20CC
153
154Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
155
156    None.
157
158Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization)
159
160    None.
161
162Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment
163Operations and the Frame Buffer)
164
165    None.
166
167Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
168
169    None.
170
171Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State
172Requests)
173
174    None.
175
176Additions to the WGL Specification
177
178    Add to the description of <piAttributes> in wglGetPixelFormatAttribivARB
179    and <pfAttributes> in wglGetPixelFormatfv:
180
181        WGL_BIND_TO_VIDEO_RGB_NV
182        WGL_BIND_TO_VIDEO_RGBA_NV
183        WGL_BIND_TO_VIDEO_RGB_AND_DEPTH_NV
184
185    Add new table entries to match criteria in description of
186    wglChoosePixelFormatARB:
187
188        Attribute                           Type        Match Criteria
189
190        WGL_BIND_TO_VIDEO_RGB_NV            boolean     exact
191        WGL_BIND_TO_VIDEO_RGBA_NV           boolean     exact
192        WGL_BIND_TO_VIDEO_RGB_AND_DEPTH_NV  boolean     exact
193
194    Add wglGetVideoDeviceNV:
195
196    The command
197
198        BOOL wglGetVideoDeviceNV(HDC hDC, int numDevices,
199                                 HPVIDEODEV hpVideoDevice)
200
201     returns an array of upto <numDevices> handles to the available video
202     devices in the array <hpVideoDevice>.  <numDevices> must be
203     non-negative, and <hpVideoDevice> must not be NULL.
204
205     It is not an error if the number of available video devices is larger
206     that <numDevices>; in that case the first <numDevices> device handles
207     are returned.  It is an error if <numDevices> is larger than the
208     number of available video devices.  The order of devices returned in
209     <hpVideoDevice> is implementation dependent.
210
211     if wglGetVideoDeviceNV fails, FALSE is returned.  To get extended
212     error information, call GetLastError.  Possible errors are as follows:
213
214     ERROR_INVALID_HANDLE           <hDC> is not a valid handle.
215
216     ERROR_INVALID_HANDLE           <hpVideoDevice> is NULL.
217
218     ERROR_INVALID_VALUE            <numDevices> is negative.
219
220     ERROR_INVALID_OPERATION        The video devices are not configured.
221
222     ERROR_RESOURCE_NOT_AVAILABLE   The number of video devices requested
223                                    are not available.
224
225
226    Add wglReleaseVideoDeviceNV:
227
228    The command
229
230        BOOL wglReleaseVideoDeviceNV(HPVIDEODEV hVideoDevice)
231
232    releases all resources associated with <hpVideoDevice>.
233
234    If wglReleaseVideoDeviceNV fails, FALSE is returned.  To get extended
235    error information, call GetLastError.  Possible errors are as follows:
236
237    ERROR_INVALID_HANDLE            <hpVideoDevice> is not a valid handle.
238
239    ERROR_INVALID_OPERATION         The video device is not allocated.
240
241
242    Add wglBindVideoImageNV and wglReleaseVideoImageNV:
243
244    The command
245
246        BOOL wglBindVideoImageNV (HPVIDEODEV hpVideoDevice,
247                                  HPBUFFERARB hPbuffer,
248                                  int iVideoBuffer);
249
250    binds <hPbuffer> to <hpVideoDevice> for subsequent scanout where
251    <iVideoBuffer> specifies that <pbuffer> contains color, alpha or
252    depth data.  Neither <pbuffer> nor <hpVideoDevice) can be NULL.
253
254    If  wglBindVideoImageNV fails, FALSE is returned.  To get extended
255    error information, call GetLastError. Possible errors are as follows:
256
257    ERROR_INVALID_HANDLE            <hPbuffer> is not a valid handle.
258
259    ERROR_INVALID_DATA              The pbuffer size is not correct.
260
261    ERROR_INVALID_OPERATION         The video device is not yet configured.
262
263
264    The command
265
266       BOOL wglReleaseVideoImageNV (HPBUFFERARB hPbuffer,
267                                    int iVideoBuffer);
268
269    releases <hPbuffer> from a previously bound video device.  The
270    parameter <iVideoBuffer> specifies that the pbuffer contains
271    color, alpha or depth data.  <hPbuffer> may not be NULL.
272
273    If  wglReleaseVideoImageNV fails, FALSE is returned. To get extended
274    error information, call GetLastError. Possible errors are as follows:
275
276    ERROR_INVALID_HANDLE            <hPbuffer> is not a valid handle.
277
278    ERROR_INVALID_DATA              <iBuffer> is not a valid value.
279
280
281    Add wglSendPbufferToVideoNV and wglGetVideoInfoNV:
282
283    The command
284
285       BOOL wglSendPbufferToVideoNV (HPBUFFER hPbuffer, int iBufferType,
286                                     unsigned long *pulCounterPbuffer,
287                                     BOOL bBlock);
288
289    indicates that rendering to the <hPbuffer> is complete and that the
290    completed frame/field contained within <hPbuffer> is ready for scan out
291    by the video device where <iBufferType> specifies that <hPbuffer>
292    contains the first field, second field, two stacked fields or a complete
293    frame. <hPbuffer> cannot be NULL.
294    An <iBufferType> of WGL_VIDEO_OUT_STACKED_FIELDS_1_2 indicates that
295    <hPbuffer> does contain field1 and field2 with field1 in the upper half
296    of <hPbuffer> and filed2 in the lower half, while
297    WGL_VIDEO_OUT_STACKED_FIELDS_2_1 indicates field2 in the upper half
298    of <hPbuffer> and filed1 in the lower half.
299    The flag <bBlock> specifies whether or not the call should block until
300    scan out of the specified frame/field is complete.
301    <pulCounterPbuffer> returns the total number of frames/fields sent to
302    the video device.
303
304    If  wglSendPbufferToVideoNV fails, FALSE is returned. To get extended
305    error information, call GetLastError. Possible errors are as follows:
306
307    ERROR_INVALID_HANDLE            <HPBUFFER> is not a valid handle.
308
309    ERROR_INVALID_DATA              <iBufferType> is not a valid value.
310
311
312    The command
313
314        BOOL wglGetVideoInfoNV (HPVIDEODEV hpVideoDevice,
315                                unsigned long *pulCounterOutputPbuffer,
316                                unsigned long *pulCounterOutputVideo);
317
318    returns in <pulCounterOutputVideo> the absolute count of vertical
319    blanks on <hpVideoDevice> since transfers were started while
320    <pulCounterOutputPbuffer> returns the count of the current pbuffer
321    being scanned out by <hpVideoDevice>.
322
323    If wglGetVideoInfoNV fails, FALSE is returned.  To get extended error
324    information, call GetLastError.  Possible errors include:
325
326    ERROR_INVALID_HANDLE             <hPVIDEODEVICE> is not a valid handle.
327
328New State
329
330    None
331
332Usage Examples
333
334    TBD
335
336Revision History:
337
338    20 February 2008
339        public release
340