xref: /third_party/openGLES/extensions/NV/WGL_NV_video_output.txt

Name 

    NV_video_output

Name Strings 

    WGL_NV_video_output

Contact 

    Thomas True, Nvidia, ttrue@nvidia.com
    Ian Williams, Nvidia, iwilliams@nvidia.com
    Martin Schwarzer, Nvidia, mschwarzer@nvidia.com

Status 

    Shipping since 2004 for NVIDIA Quadro SDI (Serial Digital Interface)

Version 

    Last Modified Date: February 20, 2008

Number 

    349

Dependencies 

    OpenGL 1.1 is required. 
    WGL_ARB_extension_string is required. 
    WGL_ARB_pixel_format is required. 
    WGL_ARB_pbuffer is required. 

Overview 

    This extension permits a color and or depth buffer of a pbuffer to
    be used for rendering and subsequent video output.  After a pbuffer 
    has been bound to a video device, subsequent color and or depth 
    rendering into that buffer is displayed on the video output.

Issues 

 1. Should the new pbuffer attributes be available through GL queries? 

    No, like other pbuffer attributes you need to query them through the 
    window system extension. This extension does not make any changes to 
    OpenGL. 

Implementation Notes

 1. Any created pbuffers must be the same resolution as that specified
    by the state of the video output device.

 2. Applications may use a single pbuffer or a collection of pbuffers
    to send frames/fields to a video device.  In the first case, an
    application should block on the call to wglSendPbufferToVideoNV()
    to ensure synchronization.  In the second caes, an application
    should utilize wglGetVideoInfoNV() in order to query vblank and 
    buffer counters for synchronization.

Intended Usage 

    1) Configure the video output device via the NVCPL API or via
       the control panel which uses the NVCPL API.

    2) Call wglChoosePixelFormatARB and find a suitable pixel format
       for rendering images.  WGL_DRAW_TO_PBUFFER and one of
       WGL_BIND_TO_VIDEO_RGB_NV, WGL_BIND_TO_VIDEO_RGBA_NV or
       WGL_BIND_TO_VIDEO_RGB_AND_DEPTH_NV must be TRUE.  The
       per-component pixel depth of the pbuffer must be equal to or 
       greater than the per-component depth of the video output.

    3) Create pbuffers and associated rendering contexts for each
       channel of video by calling wglCreatePbufferARB with one 
       of WGL_BIND_TO_VIDEO_RGB_NV, WGL_BIND_TO_VIDEO_RGBA_NV or
       WGL_BIND_TO_VIDEO_RGB_AND_DEPTH_NV tokens in the attribute 
       list set to TRUE.  Set the width and height for each pbuffer 
       to match that of the intended video output device.

    4) Call wglGetVideoDeviceNV to retrieve the handles for all 
       video devices available.  A video device handle is required
       for each video stream.

    5) Call wglBindVideoImageNV to bind each pbuffer drawable to a
       corresponding video device handle.

    6) Start transfers on each video device using the appropriate
       NVCPL API function call.

    7) Render the current frame/field for each stream to a
       pbuffer. Once rendering is complete, call
       wglSendPbufferToVideoNV() to send each frame/field to the video
       device.

    9) Render subsequent video frames or fields calling
       wglSendPbufferToVideoNV() at the completion of rendering for
       each frame/field.

    10) Stop transfers on the video device via the appropriate NVCPL
        API function call.

    11) Call wglReleaseVideoImageNV to unbind each pbuffer drawable
        from its associated video device.

New Procedures and Functions 

    DECLARE_HANDLE(HPVIDEODEV);

    BOOL wglGetVideoDeviceNV(HDC hDC, int numDevices,
                             HPVIDEODEV *hVideoDevice);

    BOOL wglReleaseVideoDeviceNV(HPVIDEODEV hVideoDevice);

    BOOL wglBindVideoImageNV (HPVIDEODEV hVideoDevice, 
                              HPBUFFERARB hPbuffer, int iVideoBuffer);

    BOOL wglReleaseVideoImageNV (HPBUFFERARB hPbuffer, int iVideoBuffer);

    BOOL wglSendPbufferToVideoNV (HPBUFFERARB hPbuffer, int iBufferType, 
                                  unsigned long *pulCounterPbuffer,
                                  BOOL bBlock);

    BOOL wglGetVideoInfoNV (HPVIDEODEV hpVideoDevice, 
                            unsigned long *pulCounterOutputPbuffer,
                            unsigned long *pulCounterOutputVideo);

New Tokens 

    Accepted by the <piAttributes> parameter of wglGetPixelFormatAttribivARB, 
    wglGetPixelFormatAttribfvARB, and the <piAttribIList> and <pfAttribIList>
    parameters of wglChoosePixelFormatARB and wglCreatePbufferARB: 

        WGL_BIND_TO_VIDEO_RGB_NV                        0x20C0
        WGL_BIND_TO_VIDEO_RGBA_NV                       0x20C1
        WGL_BIND_TO_VIDEO_RGB_AND_DEPTH_NV              0x20C2

    Accepted by the <iVideoBuffer> parameter of wglBindVideoImageNV and 
    wglReleaseVideoImageNV: 

        WGL_VIDEO_OUT_COLOR_NV                          0x20C3
        WGL_VIDEO_OUT_ALPHA_NV                          0x20C4
        WGL_VIDEO_OUT_DEPTH_NV                          0x20C5
        WGL_VIDEO_OUT_COLOR_AND_ALPHA_NV                0x20C6
        WGL_VIDEO_OUT_COLOR_AND_DEPTH_NV                0x20C7

    Accepted by the <iBufferType> parameter of wglSendPbufferToVideoNV:

        WGL_VIDEO_OUT_FRAME                             0x20C8
        WGL_VIDEO_OUT_FIELD_1                           0x20C9
        WGL_VIDEO_OUT_FIELD_2                           0x20CA
        WGL_VIDEO_OUT_STACKED_FIELDS_1_2                0x20CB
        WGL_VIDEO_OUT_STACKED_FIELDS_2_1                0x20CC

Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 

    None. 

Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 

    None. 

Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 
Operations and the Frame Buffer) 

    None. 

Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 

    None. 

Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State 
Requests) 

    None. 

Additions to the WGL Specification 

    Add to the description of <piAttributes> in wglGetPixelFormatAttribivARB 
    and <pfAttributes> in wglGetPixelFormatfv: 

        WGL_BIND_TO_VIDEO_RGB_NV
        WGL_BIND_TO_VIDEO_RGBA_NV
        WGL_BIND_TO_VIDEO_RGB_AND_DEPTH_NV

    Add new table entries to match criteria in description of 
    wglChoosePixelFormatARB: 

        Attribute                           Type        Match Criteria 

        WGL_BIND_TO_VIDEO_RGB_NV            boolean     exact
        WGL_BIND_TO_VIDEO_RGBA_NV           boolean     exact
        WGL_BIND_TO_VIDEO_RGB_AND_DEPTH_NV  boolean     exact

    Add wglGetVideoDeviceNV:

    The command

        BOOL wglGetVideoDeviceNV(HDC hDC, int numDevices, 
                                 HPVIDEODEV hpVideoDevice)

     returns an array of upto <numDevices> handles to the available video 
     devices in the array <hpVideoDevice>.  <numDevices> must be 
     non-negative, and <hpVideoDevice> must not be NULL.

     It is not an error if the number of available video devices is larger
     that <numDevices>; in that case the first <numDevices> device handles
     are returned.  It is an error if <numDevices> is larger than the 
     number of available video devices.  The order of devices returned in
     <hpVideoDevice> is implementation dependent.

     if wglGetVideoDeviceNV fails, FALSE is returned.  To get extended
     error information, call GetLastError.  Possible errors are as follows:

     ERROR_INVALID_HANDLE           <hDC> is not a valid handle. 

     ERROR_INVALID_HANDLE           <hpVideoDevice> is NULL.

     ERROR_INVALID_VALUE            <numDevices> is negative.

     ERROR_INVALID_OPERATION        The video devices are not configured.

     ERROR_RESOURCE_NOT_AVAILABLE   The number of video devices requested
                                    are not available.


    Add wglReleaseVideoDeviceNV:

    The command 
    
        BOOL wglReleaseVideoDeviceNV(HPVIDEODEV hVideoDevice) 

    releases all resources associated with <hpVideoDevice>.

    If wglReleaseVideoDeviceNV fails, FALSE is returned.  To get extended 
    error information, call GetLastError.  Possible errors are as follows:

    ERROR_INVALID_HANDLE            <hpVideoDevice> is not a valid handle.

    ERROR_INVALID_OPERATION         The video device is not allocated.


    Add wglBindVideoImageNV and wglReleaseVideoImageNV: 

    The command 

        BOOL wglBindVideoImageNV (HPVIDEODEV hpVideoDevice,
                                  HPBUFFERARB hPbuffer, 
                                  int iVideoBuffer);

    binds <hPbuffer> to <hpVideoDevice> for subsequent scanout where
    <iVideoBuffer> specifies that <pbuffer> contains color, alpha or
    depth data.  Neither <pbuffer> nor <hpVideoDevice) can be NULL.  

    If  wglBindVideoImageNV fails, FALSE is returned.  To get extended 
    error information, call GetLastError. Possible errors are as follows: 

    ERROR_INVALID_HANDLE            <hPbuffer> is not a valid handle. 

    ERROR_INVALID_DATA              The pbuffer size is not correct.

    ERROR_INVALID_OPERATION         The video device is not yet configured.


    The command

       BOOL wglReleaseVideoImageNV (HPBUFFERARB hPbuffer,
                                    int iVideoBuffer);

    releases <hPbuffer> from a previously bound video device.  The
    parameter <iVideoBuffer> specifies that the pbuffer contains
    color, alpha or depth data.  <hPbuffer> may not be NULL.

    If  wglReleaseVideoImageNV fails, FALSE is returned. To get extended 
    error information, call GetLastError. Possible errors are as follows: 

    ERROR_INVALID_HANDLE            <hPbuffer> is not a valid handle. 

    ERROR_INVALID_DATA              <iBuffer> is not a valid value. 
        

    Add wglSendPbufferToVideoNV and wglGetVideoInfoNV: 

    The command

       BOOL wglSendPbufferToVideoNV (HPBUFFER hPbuffer, int iBufferType, 
                                     unsigned long *pulCounterPbuffer,
                                     BOOL bBlock);

    indicates that rendering to the <hPbuffer> is complete and that the 
    completed frame/field contained within <hPbuffer> is ready for scan out 
    by the video device where <iBufferType> specifies that <hPbuffer>
    contains the first field, second field, two stacked fields or a complete 
    frame. <hPbuffer> cannot be NULL. 
    An <iBufferType> of WGL_VIDEO_OUT_STACKED_FIELDS_1_2 indicates that
    <hPbuffer> does contain field1 and field2 with field1 in the upper half 
    of <hPbuffer> and filed2 in the lower half, while 
    WGL_VIDEO_OUT_STACKED_FIELDS_2_1 indicates field2 in the upper half 
    of <hPbuffer> and filed1 in the lower half.
    The flag <bBlock> specifies whether or not the call should block until 
    scan out of the specified frame/field is complete.
    <pulCounterPbuffer> returns the total number of frames/fields sent to 
    the video device.

    If  wglSendPbufferToVideoNV fails, FALSE is returned. To get extended 
    error information, call GetLastError. Possible errors are as follows: 

    ERROR_INVALID_HANDLE            <HPBUFFER> is not a valid handle. 

    ERROR_INVALID_DATA              <iBufferType> is not a valid value. 
        

    The command

        BOOL wglGetVideoInfoNV (HPVIDEODEV hpVideoDevice, 
                                unsigned long *pulCounterOutputPbuffer,
                                unsigned long *pulCounterOutputVideo);

    returns in <pulCounterOutputVideo> the absolute count of vertical 
    blanks on <hpVideoDevice> since transfers were started while 
    <pulCounterOutputPbuffer> returns the count of the current pbuffer 
    being scanned out by <hpVideoDevice>.

    If wglGetVideoInfoNV fails, FALSE is returned.  To get extended error 
    information, call GetLastError.  Possible errors include:

    ERROR_INVALID_HANDLE             <hPVIDEODEVICE> is not a valid handle.

New State

    None 

Usage Examples

    TBD

Revision History:

    20 February 2008
        public release