home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / dvdif.idl < prev    next >
Text File  |  1998-04-25  |  32KB  |  802 lines
  1. //==========================================================================;
  2. //
  3. //  THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
  4. //  KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  5. //  IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR
  6. //  PURPOSE.
  7. //
  8. //  Copyright (c) 1992 - 1997  Microsoft Corporation.  All Rights Reserved.
  9. //
  10. //--------------------------------------------------------------------------;
  11.  
  12. // 
  13. // DirectShow interfaces to control playback of a DVD filter graph.
  14. //
  15.  
  16. // forward declarations - these are the interfaces declared in this file
  17.  
  18. import "unknwn.idl";
  19. import "objidl.idl";
  20.  
  21.  
  22. interface IDvdControl;
  23. interface IDvdInfo;
  24. interface IDvdGraphBuilder ;
  25.  
  26.  
  27. //==========================================================================
  28. //==========================================================================
  29. //
  30. // typedefs used by IDvdControl and IDvdInfo interfaces.
  31. //
  32. //==========================================================================
  33. //==========================================================================
  34.  
  35. typedef enum tagDVD_DOMAIN {
  36.     // The DVD_DOMAIN is used to indicate the stat of a DVD player.
  37.     DVD_DOMAIN_FirstPlay=1,         // doing default initialization of a dvd disc
  38.     DVD_DOMAIN_VideoManagerMenu,  // displaying menus for whole disc
  39.     DVD_DOMAIN_VideoTitleSetMenu, // displaying menus for current title set
  40.     DVD_DOMAIN_Title,             // displaying current title
  41.     DVD_DOMAIN_Stop               // player is in stopped state
  42. } DVD_DOMAIN;
  43.  
  44. typedef enum tagDVD_MENU_ID {
  45.     DVD_MENU_Title = 2,     // to choose a title from any VTS in a DVD-Video volume
  46.     DVD_MENU_Root = 3,      // main menu for a specific VTS 
  47.     DVD_MENU_Subpicture =4, // to choose subpicture stream in a VTS
  48.     DVD_MENU_Audio = 5,     // to choose audio stream in a VTS
  49.     DVD_MENU_Angle = 6,     // to choose angle num in a VTS
  50.     DVD_MENU_Chapter = 7    // to choose a chapter in a VTS
  51.     // the Root menu always provides a means of getting to to Subpicture, Audio, 
  52.     // Angle and Chapter menus if they exist.
  53. } DVD_MENU_ID;
  54.  
  55. typedef enum tagDVD_DISC_SIDE {
  56.     DVD_SIDE_A = 1,
  57.     DVD_SIDE_B = 2
  58. } DVD_DISC_SIDE;
  59.  
  60.  
  61. typedef enum tagDVD_PREFERRED_DISPLAY_MODE
  62. {
  63.     // DVD_PREFERRED_DISPLAY_MODE is used to indicate the user's
  64.     // preferred window aspect ratio and preferred method of converion of
  65.     // 16*9 content to a 4*3 window aspect ratio.  Pan-scan and letterboxing are
  66.     // the two conversion methods.  This enum is used to indicate only a preference of 
  67.     // conversion mechinism since some content can only be converted using one 
  68.     // of these methods.  4*3 content is converted to a 16*9 window always by using
  69.     // "reverse" letterboxing where black bars are added to the right and left 
  70.     // sides of the display instead of the top and bottom of the display as in the 16*9
  71.     // to 4*3 conversion useing letterboxing.
  72.     DISPLAY_CONTENT_DEFAULT = 0,    // default to content
  73.     DISPLAY_16x9 = 1,               // 16x9 display
  74.     DISPLAY_4x3_PANSCAN_PREFERRED = 2,   // 4x3 display with pan-scan preferrence
  75.     DISPLAY_4x3_LETTERBOX_PREFERRED = 3   // 4x3 display with letterbox preferrence
  76.  
  77. } DVD_PREFERRED_DISPLAY_MODE;
  78.  
  79. typedef WORD DVD_REGISTER;
  80. typedef DVD_REGISTER    GPRMARRAY[16]; // DVD-Video 1.0 has 16 16-bit General Parameter Registers
  81. typedef DVD_REGISTER    SPRMARRAY[24]; // DVD-Video 1.0 has 24 16-bit System Parameter Registers
  82.  
  83. typedef struct tagDVD_ATR 
  84. {
  85.     //
  86.     // Refer to the DVD-Video 1.0 spec to parse these structures.
  87.     //
  88.     ULONG    ulCAT;     // VMG_CAT if this is for a volume; or VTS_CAT 
  89.             //      if this is for a Video Title Set (VTS)
  90.     BYTE    pbATRI[768];// All stream attributes for menu and title from bytes
  91.             //      256 to 1023 of VMGI or VTSI.
  92. } DVD_ATR;
  93.  
  94.  
  95. typedef BYTE DVD_VideoATR[2];   // video stream attributes.  See DVD-Video spec.
  96. typedef BYTE DVD_AudioATR[8];   // audio stream attributes.  See DVD-Video spec.
  97. typedef BYTE DVD_SubpictureATR[6]; // subpicture stream attributes.  See DVD-Video spec.
  98.  
  99.  
  100. // DVD Timecode is BCD encoded in this format: 0xHhMmSsFf, where
  101. //      H is tens of hours
  102. //      h is hours
  103. //      M is tens of minutes
  104. //      m is minutes
  105. //      S is tens of seconds
  106. //      s is seconds
  107. //      F is tens of frames
  108. //      f is frames
  109. // Note that you must know the frame rate to interperate the frame count as time.
  110. typedef enum tagDVD_FRAMERATE
  111. {
  112.     DVD_FPS_25 =1, // 25 frames per second
  113.     DVD_FPS_30NonDrop = 3 // exactly 30 frames per second
  114. } DVD_FRAMERATE;
  115.  
  116. cpp_quote("typedef struct tagDVD_TIMECODE")
  117. cpp_quote("{")
  118. cpp_quote("   ULONG Hours1    :4; // Hours")
  119. cpp_quote("   ULONG Hours10  :4; // Tens of Hours ")
  120. cpp_quote("")
  121. cpp_quote("   ULONG Minutes1  :4; // Minutes ")
  122. cpp_quote("   ULONG Minutes10:4; // Tens of Minutes ")
  123. cpp_quote("")
  124. cpp_quote("   ULONG Seconds1  :4; // Seconds ")
  125. cpp_quote("   ULONG Seconds10:4; // Tens of Seconds ")
  126. cpp_quote("")
  127. cpp_quote("   ULONG Frames1   :4; // Frames ")
  128. cpp_quote("   ULONG Frames10 :2; // Tens of Frames ")
  129. cpp_quote("")
  130. cpp_quote("   ULONG FrameRateCode: 2; // use DVD_FRAMERATE to indicate frames/sec and drop/non-drop")
  131. cpp_quote("} DVD_TIMECODE;")
  132.  
  133.  
  134. typedef struct tagDVD_PLAYBACK_LOCATION 
  135. {
  136.     //
  137.     // TitleNum & ChapterNum or TitleNum & TimeCode are sufficient to save 
  138.     // playback location for Once_Sequential_PGC_Titles.
  139.     //
  140.     ULONG   TitleNum;   // title number for whole disc (TTN not VTS_TTN)
  141.     ULONG   ChapterNum; // part-of-title number with title. 0xffffffff if not Once_Sequential_PGC_Title
  142.     ULONG   TimeCode;   // use DVD_TIMECODE for current playback time. 0xffffffff if not Once_Sequential_PGC_Title
  143.  
  144. } DVD_PLAYBACK_LOCATION;
  145.  
  146. typedef DWORD VALID_UOP_SOMTHING_OR_OTHER;
  147.  
  148. // Parental Level Information
  149. cpp_quote ("#define DVD_PARENTAL_LEVEL_8    0x8000")
  150. cpp_quote ("#define DVD_PARENTAL_LEVEL_7    0x4000")
  151. cpp_quote ("#define DVD_PARENTAL_LEVEL_6    0x2000")
  152. cpp_quote ("#define DVD_PARENTAL_LEVEL_5    0x1000")
  153. cpp_quote ("#define DVD_PARENTAL_LEVEL_4    0x0800")
  154. cpp_quote ("#define DVD_PARENTAL_LEVEL_3    0x0400")
  155. cpp_quote ("#define DVD_PARENTAL_LEVEL_2    0x0200")
  156. cpp_quote ("#define DVD_PARENTAL_LEVEL_1    0x0100")
  157.  
  158.  
  159. //==========================================================================
  160. //==========================================================================
  161. // IDvdControl interface -- Basic DVD-Video playback control.
  162. // This modeled after the app control of a player specified in Annex J 
  163. // of the DVD Video spec.  IDvdInfo can be used to get information useful
  164. // in using IDvdControl
  165. //==========================================================================
  166. //==========================================================================
  167.  
  168. [
  169. object,
  170. uuid(A70EFE61-E2A3-11d0-A9BE-00AA0061BE93),
  171. pointer_default(unique)
  172. ]
  173.  
  174. interface IDvdControl : IUnknown {
  175.     import "unknwn.idl";
  176.     
  177.     // TitlePlay 
  178.     // Start playing the specified title number. 
  179.     // Title numbers range between 1 and 99.
  180.     HRESULT TitlePlay
  181.     ( [in]  ULONG   uiTitle
  182.     );
  183.  
  184.     // ChapterPlay
  185.     // Start playing at the specified chapter (or part-of-title) 
  186.     // within the specified title.  Chapters range from 1 to 999.
  187.     HRESULT ChapterPlay
  188.     ( [in]  ULONG   uiTitle, 
  189.       [in]  ULONG   uiChapter
  190.     );
  191.  
  192.     // TimePlay
  193.     // Start playing at the specified time within the specified title.
  194.     // NOTE: the actual start time will be the closest sync point before
  195.     // or equal to the specified frame number.
  196.     HRESULT TimePlay
  197.     ( [in]  ULONG   uiTitle,
  198.       [in]  ULONG   bcdTime  // use DVD_TIMECODE.  Framerate code is ignored.
  199.     );
  200.  
  201.     // StopForResume
  202.     // Stop playback after saving resume information.  DVD Navigator transfers to the DVD "Stop State" and 
  203.     // (same as DVD_DOMAIN_Stop), but filter graph remains in DirectShow's Run state.
  204.     HRESULT StopForResume();     
  205.  
  206.     // GoUp
  207.     // Start playback of the program chain currently authored as the "GoUp_PGCN".
  208.     HRESULT GoUp();     
  209.  
  210.     // TimeSearch
  211.     // Start playing at the specified time within the current title.
  212.     // NOTE: the actual start time will be the closest sync point before
  213.     // or equal to the specified frame number.
  214.     HRESULT TimeSearch
  215.     ( [in]  ULONG   bcdTime  // use DVD_TIMECODE.  Framerate code is ignored.
  216.     );      
  217.  
  218.     // ChapterSearch
  219.     // Start playing at the specified chapter (or part-of-title) within
  220.     // the current title.
  221.     HRESULT ChapterSearch
  222.     ( [in]  ULONG   Chapter
  223.     );      
  224.  
  225.     // PrevPGSearch
  226.     // Start playing at the beginning of the previous DVD "program".
  227.     // For One-Sequential_PGC_Titles (which includes most titles) a program 
  228.     // is equivalent to a chapter, otherwise a program is part of a chapter. 
  229.     HRESULT PrevPGSearch();     
  230.  
  231.     // TopPGSearch
  232.     // Start playing from the beginning of they current program.
  233.     HRESULT TopPGSearch();      
  234.  
  235.     // NextPGSearch
  236.     // Start playing from the beginning of the next program.
  237.     HRESULT NextPGSearch();     
  238.  
  239.     // ForwardScan
  240.     // Set forward play at the specified speed.  
  241.     //      dwSpeed == 1 is normal play
  242.     //      dwSpeed  < 1 is slow play
  243.     //      dwSpeed  > 1 is fast play
  244.     // For dwSpeed != 1, audio and subpicture is muted.
  245.     HRESULT ForwardScan
  246.     ( [in]  double  dwSpeed
  247.     );      
  248.  
  249.     // BackwardScan
  250.     // Set reverse play at the specified speed.  
  251.     //      dwSpeed == 1 is normal play speed in reverse
  252.     //      dwSpeed  < 1 is slow play in reverse
  253.     //      dwSpeed  > 1 is fast play in reverse
  254.     // For reverse play, audio and subpicture are always muted.
  255.     HRESULT BackwardScan
  256.     ( [in]  double  dwSpeed
  257.     );      
  258.  
  259.     // MenuCall
  260.     // Start playback of the Menu specified by an enum DVD_MENU_ID.
  261.     HRESULT MenuCall
  262.     ( [in]  DVD_MENU_ID   MenuID  
  263.     );      
  264.  
  265.     // Resume
  266.     // Returns to title playback in DVD_DOMAIN_Title. This is typically
  267.     // done after MenuCall which puts the DVD Navigator in 
  268.     // DVD_DOMAIN_VideoTitleSetMenu or DVD_DOMAIN_VideoManagerMenu.
  269.     HRESULT Resume();       
  270.  
  271.     // UpperButtonSelect
  272.     // Selects the button above the current button.
  273.     // "Selecting" a DVD button simply highlights the button but does
  274.     // not "Activate" the button.  Selecting is the Windows equivalent 
  275.     // to tabbing to a button but not pressing the space bar or enter key.
  276.     // Activating is the Windows equivalent of pressing the space bar or
  277.     // enter key after tabbing to a button.
  278.     HRESULT UpperButtonSelect();        
  279.  
  280.     // LowerButtonSelect
  281.     // Selects the button below the current button.
  282.     HRESULT LowerButtonSelect();        
  283.  
  284.     // LeftButtonSelect
  285.     // Selects the button to the left of the current button.
  286.     HRESULT LeftButtonSelect();     
  287.  
  288.     // RightButtonSelect
  289.     // Selects the button to the right of the current button.
  290.     HRESULT RightButtonSelect();        
  291.  
  292.     // ButtonActivate
  293.     // Activates current button.
  294.     HRESULT ButtonActivate();       
  295.  
  296.     // ButtonSelectAndActivate
  297.     // Selects and then activates the button specified by the user.  
  298.     // uiButton is intended to be a number entered by a user corresponding
  299.     // to button numbers currently displayed on screen.  
  300.     // Button numbers range from 1 to 36.
  301.     HRESULT ButtonSelectAndActivate
  302.     ( [in]  ULONG   uiButton
  303.     );      
  304.  
  305.     // StillOff
  306.     // Releases any current still if there are no available buttons.
  307.     // This includes VOBU stills, Cell stills, and PGC stills, whether the 
  308.     // still is infinite.  When buttons are available, stills are released by
  309.     // activating a button.  Note this does not release a Pause.
  310.     HRESULT StillOff();     
  311.  
  312.     // PauseOn
  313.     // Freezes playback and any internal timers. This is similar to
  314.     // IMediaControl::Pause()
  315.     HRESULT PauseOn();      
  316.  
  317.     // PauseOff
  318.     // Releases a Pause.  
  319.     HRESULT PauseOff();     
  320.  
  321.     // MenuLanguageSelect
  322.     // Selects the default language for menus.  Languages are specified with
  323.     // Windows standard LCIDs.  LCIDs can be created from ISO-639 codes with
  324.     // MAKELCID( MAKELANGID(wISO639LangID ,SUBLANG_DEFAULT ), SORT_DEFAULT )
  325.     // NOTE: MAKELANGID seems to have a bug so 'jp' may have to be used 
  326.     // instead of 'ja' for the ISO639 code for Japanese.
  327.     // MenuLanguageSelect may only called from the DVD Stop state (DVD_DOMAIN_Stop).
  328.     HRESULT MenuLanguageSelect
  329.     ( [in]  LCID    Language
  330.     );      
  331.  
  332.     // AudioStreamChange
  333.     // Changes the current audio stream.
  334.     HRESULT AudioStreamChange
  335.     ( [in]  ULONG   nAudio
  336.     );      
  337.  
  338.     // SubpictureStreamChange
  339.     // Changes the current subpicture stream number to nSubpic, and toggles 
  340.     // its display.
  341.     HRESULT SubpictureStreamChange
  342.     ( [in]  ULONG   nSubPicture,
  343.       [in]  BOOL    bDisplay
  344.     );      
  345.  
  346.     // AngleChange
  347.     // Changes the current angle number.
  348.     HRESULT AngleChange
  349.     ( [in]  ULONG   ulAngle
  350.     );      
  351.  
  352.     // ParentalLevelSelect
  353.     // Selects the current player parental level between 1 and 8.  The
  354.     // defined parental levels are listed below :
  355.     //
  356.     //      Level   Rating  
  357.     //      -----   ------  
  358.     //
  359.     //      1       G       
  360.     //      3       PG      
  361.     //      4       PG13    
  362.     //      6       R       
  363.     //      7       NC17    
  364.     // Higher levels can play lower level content; lower levels cannot play 
  365.     // higher level content.  The DVD Navigator provides no restriction on
  366.     // setting the parental level.  DVD player application may enforce 
  367.     // restriction on parental level setting, such as password protection for 
  368.     // raising the current parental level.  Parental Management is disabled in
  369.     // the Navigator by default.
  370.     //
  371.     //      Note : To disable parental management, pass 0xffffffff for ulParentalLevel
  372.     //                 If parental management is disabled, then the player will play the
  373.     //                 first PGC in a parental block regardless of parental IDs.
  374.     //
  375.     HRESULT ParentalLevelSelect
  376.     ( [in]  ULONG   ulParentalLevel  
  377.     );      
  378.  
  379.     // ParentalCountrySelect
  380.     // Sets the country in which to interpret the the Parental Level.
  381.     // The country specified using the Alpha-2 code of the ISO-3166 standard,
  382.     // with the addition of 'ZZ' 
  383.     HRESULT ParentalCountrySelect
  384.     ( [in]  WORD    wCountry
  385.     );      
  386.  
  387.     // KaraokeAudioPresentationModeChange
  388.     // Sets the Karaoke audio mode.  
  389.     // NOTE: This and all other Karoke support is currently not implemented.
  390.     HRESULT KaraokeAudioPresentationModeChange
  391.     ( [in] ULONG    ulMode
  392.     );      
  393.  
  394.     // VideoModePreferrence
  395.     // The user can specify the preferred display mode that should
  396.     // be used to display content. The parameter is a ULONG that has
  397.     // one of the values defined in DVD_PREFERRED_DISPLAY_MODE
  398.     HRESULT VideoModePreferrence
  399.     ( [in]  ULONG    ulPreferredDisplayMode
  400.     );
  401.     
  402.     // SetRoot
  403.     // Sets the root directory containing the DVD-Video volume. 
  404.     // Can only be called from the DVD Stop State (DVD_DOMAIN_Stop).
  405.     // If the root directory is not successfully set before 
  406.     // IMediaControl::Play is called, the first drive starting from c:
  407.     // containing a VIDEO_TS directory in the top level directory
  408.     // will be used as the root.
  409.     HRESULT SetRoot
  410.     ( [in]  LPCWSTR     pszPath
  411.     );        
  412.  
  413.     // MouseActivate
  414.     // This is typically called in response to a mouse click.
  415.     // The specified point within the display window is to see if it is
  416.     // within a current DVD button's highlight rect.  If it is, that 
  417.     // button is first selected, then activated.  
  418.     // NOTE: DVD Buttons do not all necessarily have highlight rects,
  419.     // button rects can overlap, and button rects do not always
  420.     // correspond to the visual representation of DVD buttons.
  421.     HRESULT MouseActivate       // typically called after a mouse click
  422.     ( [in]  POINT       point
  423.     );
  424.  
  425.     // MouseSelect
  426.     // This is typically called in response to a mouse move within the 
  427.     // display window.
  428.     // The specified point within the display window is to see if it is
  429.     // within a current DVD button's highlight rect.  If it is, that 
  430.     // button is selected.
  431.     // NOTE: DVD Buttons do not all necessarily have highlight rects,
  432.     // button rects can overlap, and button rects do not always
  433.     // correspond to the visual representation of DVD buttons.
  434.     HRESULT MouseSelect         // typically called after a mouse move
  435.     ( [in]  POINT       point
  436.     );
  437.     
  438.     // ChapterPlayAutoStop
  439.     // Start playing at the specified chapter within the specified title
  440.     // and play the number of chapters specified by the third parameter.
  441.     // Chapters range from 1 to 999.
  442.     HRESULT ChapterPlayAutoStop
  443.     ( [in] ULONG ulTitle,           // title number
  444.       [in] ULONG ulChapter,         // chapter number to start playback
  445.       [in] ULONG ulChaptersToPlay   // number of chapters to play from the start chapter
  446.     );
  447. }
  448.  
  449.  
  450.  
  451. //==========================================================================
  452. //==========================================================================
  453. // IDvdInfo interface -- allow an app to query for attributes of available 
  454. // DVD titles and DVD player status.  Also allow for control of a DVD 
  455. // player beyond Annex J in the DVD spec.
  456. //==========================================================================
  457. //==========================================================================
  458.  
  459. [
  460. object,
  461. uuid(A70EFE60-E2A3-11d0-A9BE-00AA0061BE93),
  462. pointer_default(unique)
  463. ]
  464.  
  465. interface IDvdInfo : IUnknown {
  466.     import "unknwn.idl";
  467.  
  468.     // GetCurrentDomain
  469.     // Returns the current DVD Domain of the DVD player.
  470.     HRESULT GetCurrentDomain
  471.     ( [out] DVD_DOMAIN *pDomain 
  472.     );
  473.  
  474.     // GetCurrentLocation
  475.     // Returns information sufficient to restart playback of a video
  476.     // from the current playback location in titles that don't explicitly
  477.     // disable seeking to the current location.
  478.     HRESULT GetCurrentLocation
  479.     ( [out] DVD_PLAYBACK_LOCATION *pLocation
  480.     );
  481.  
  482.     // GetTotalTitleTime
  483.     // Return the total playback time for the current title.  Only works
  484.     // for One_Sequential_PGC_Titles.
  485.     HRESULT GetTotalTitleTime
  486.     ( [out] ULONG * pTotalTime // use DVD_TIMECODE.
  487.     );
  488.  
  489.     // GetCurrentButton
  490.     // Indicates the number of currently available buttons and the current
  491.     // selected button number. If buttons are not present it returns 0 for
  492.     // both pnButtonsAvailable and pnCurrentButton
  493.     HRESULT GetCurrentButton
  494.     ( [out] ULONG *    pnButtonsAvailable,
  495.       [out] ULONG *    pnCurrentButton
  496.     );
  497.  
  498.     // GetCurrentAngle
  499.     // Indicates the number of currently available angles and the current
  500.     // selected angle number.  If *pnAnglesAvailable==1, then the current
  501.     // video is not multiangle.
  502.     HRESULT GetCurrentAngle
  503.     ( [out] ULONG *    pnAnglesAvailable,
  504.       [out] ULONG *    pnCurrentAngle
  505.     );
  506.  
  507.     // GetCurrentAudio
  508.     // Indicates the number of currently available audio streams and 
  509.     // the current selected audio stream number.
  510.     // This only work when in DVD_DOMAIN_Title.
  511.     HRESULT GetCurrentAudio
  512.     ( [out] ULONG *    pnStreamsAvailable,
  513.       [out] ULONG *    pnCurrentStream
  514.     );
  515.  
  516.     // GetCurrentSubpicture
  517.     // Indicates the number of currently available subpicture streams,
  518.     // the current selected subpicture stream number, and if the 
  519.     // subpicture display is currently disabled.  Subpicture streams 
  520.     // authored as Forcedly Activated stream will be displayed even if
  521.     // subpicture display has been disabled by the app with 
  522.     // IDVDControl::SubpictureChangeStream.
  523.     // This only work when in DVD_DOMAIN_Title.
  524.     HRESULT GetCurrentSubpicture
  525.     ( [out] ULONG *    pnStreamsAvailable,
  526.       [out] ULONG *    pnCurrentStream,
  527.       [out] BOOL *     pIsDisabled
  528.     );
  529.  
  530.     // GetCurrentUOPS
  531.     // Indicates which IDVDControl methods are currently valid.  DVD titles
  532.     // can enable or disable individual user operations at almost any point 
  533.     // during playback.
  534.     HRESULT GetCurrentUOPS  
  535.     ( [out] VALID_UOP_SOMTHING_OR_OTHER *    pUOP
  536.     );
  537.  
  538.     // GetAllSPRMs
  539.     // Returns the current contents of all System Parameter Registers.
  540.     // See DVD-Video spec for use of individual registers.
  541.     HRESULT GetAllSPRMs
  542.     ( [out] SPRMARRAY * pRegisterArray
  543.     );
  544.  
  545.     // GetAllGPRMs
  546.     // Returns the current contents of all General Parameter Registers.
  547.     // Use of GPRMs is title specific. 
  548.     HRESULT GetAllGPRMs
  549.     ( [out] GPRMARRAY * pRegisterArray
  550.     );
  551.  
  552.     // GetAudioLanguageString
  553.     // Returns the language of the specified stream within the current
  554.     // title.  Does not return languages for menus.  Sets *pLanguage=0 if
  555.     // if the stream does not include language.
  556.     // Use GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize)
  557.     // to create a human readable string name from the result LCID.
  558.     HRESULT GetAudioLanguage
  559.     ( [in]  ULONG        nStream, 
  560.       [out] LCID *       pLanguage
  561.     );
  562.  
  563.     // GetSubpictureLanguageString
  564.     // Returns the language of the specified stream within the current
  565.     // title.  Does not return languages for menus.  Sets *pLanguage=0 if
  566.     // if the stream does not include language.
  567.     // Use GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize)
  568.     // to create a human readable string name from the result LCID.
  569.     HRESULT GetSubpictureLanguage
  570.     ( [in]  ULONG        nStream, 
  571.       [out] LCID *       pLanguage
  572.     );
  573.  
  574.     // GetTitleAttributes
  575.     // Returns attributes of all video, audio, and subpicture 
  576.     // streams for the specified title including menus.  
  577.     // If nTitle == 0xffffffff, attributes for the current title are returned.
  578.     HRESULT GetTitleAttributes
  579.     ( [in]  ULONG       nTitle, // requested title number
  580.       [out] DVD_ATR *   pATR 
  581.     );
  582.  
  583.     // GetVMGAttributes
  584.     // Returns attributes of all video, audio, and subpicture 
  585.     // streams for Video Manager Menus.  Some menus, such as the DVD_MENU_Title
  586.     // are in a separate group of streams called the VMG (Video Manager) and
  587.     // are not associated with any particular title number.
  588.     HRESULT GetVMGAttributes
  589.     ( [out] DVD_ATR *   pATR 
  590.     );
  591.  
  592.     // GetCurrentVideoAttributes
  593.     // Returns the video attributes for the current title or menu.
  594.     HRESULT GetCurrentVideoAttributes
  595.     ( [out] DVD_VideoATR *pATR 
  596.     );
  597.  
  598.     // GetCurrentAudioAttributes
  599.     // Returns the video attributes for the stream in the current 
  600.     // title or menu.
  601.     HRESULT GetCurrentAudioAttributes
  602.     ( [out] DVD_AudioATR *pATR 
  603.     );
  604.  
  605.     // GetCurrentSubpictureAttributes
  606.     // Returns the video attributes for the stream in the current 
  607.     // title or menu.
  608.     HRESULT GetCurrentSubpictureAttributes
  609.     ( [out] DVD_SubpictureATR *pATR 
  610.     );
  611.  
  612.  
  613.     // GetCurrentVolumeInfo
  614.     // Returns current DVD volume info.
  615.     HRESULT GetCurrentVolumeInfo
  616.     ( [out] ULONG *pNumOfVol,   // number of volumes (disc sides?) in a volume set
  617.       [out] ULONG *pThisVolNum, // volume number for this root directory
  618.       [out] DVD_DISC_SIDE *pSide, // current disc side
  619.       [out] ULONG *pNumOfTitles // number of titles available in this volume
  620.     );
  621.  
  622.  
  623.     // GetDVDTextInfo
  624.     // Returns the TXTDT_MG structure, which can contain text descriptions for title
  625.     // name, volume name, producer name, vocalist name, etc. in various languages.
  626.     // refer to Section 4.1.6 and Annex A of the DVD-Video spec.
  627.     // If the buffer size passed in is insufficient (for example if cbBufSize==0),
  628.     // then E_OUTOFMEMORY is returned, and *pcbActualSize is set to the required size.
  629.     HRESULT GetDVDTextInfo
  630.     ( [out, size_is(cbBufSize)] BYTE *pTextManager, 
  631.       [in]  ULONG cbBufSize,        // buffer size passed in
  632.       [out] ULONG *pcbActualSize    // amount of actual data return
  633.     );
  634.  
  635.     //  GetPlayerParentalLevel
  636.     //  Returns the current parental level and the current country code
  637.     //  that has been set in the system registers in player. 
  638.     //  See Table 3.3.4-1 of the DVD-Video spec for the defined parental levels.
  639.     //  Valid Parental Levels = 1..8 if parental management is enabled
  640.     //  0xffffffff if parental management is disabled
  641.     //  See ISO3166 : Alpha-2 Code for the country codes.
  642.     HRESULT GetPlayerParentalLevel
  643.     ( [out] ULONG *pParentalLevel,    // current parental level
  644.       [out] ULONG *pCountryCode       // current country code
  645.     );
  646.     
  647.     //  GetNumberOfChapters
  648.     //  Returns the number of chapters that are defined for a
  649.     //  given title.
  650.     HRESULT GetNumberOfChapters
  651.     ( [in]  ULONG ulTitle,              // Title for which number of chapters is requested
  652.       [out] ULONG *pNumberOfChapters    // Number of chapters for the specified title
  653.     );
  654.  
  655.     // GetTitleParentalLevels
  656.     // Returns the parental levels that are defined for a
  657.     // particular title. pParentalLevels will be combination
  658.     // of DVD_PARENTAL_LEVEL_8, DVD_PARENTAL_LEVEL_6, or 
  659.     // DVD_PARENTAL_LEVEL_1 "OR"ed together
  660.     HRESULT GetTitleParentalLevels
  661.     ( [in] ULONG ulTitle,           // Title for which parental levels are requested
  662.       [out] ULONG *pParentalLevels  // Parental levels defined for the title "OR"ed together
  663.     );
  664.  
  665.     // GetRoot
  666.     // Returns the root directory that is set in the player. If a valid root
  667.     // has been found, it returns the root string. Otherwise, it returns 0 for
  668.     // pcbActualSize indicating that a valid root directory has not been found
  669.     // or initialized.
  670.     HRESULT GetRoot
  671.     ( [out, size_is(cbBufSize)] LPTSTR pRoot,    // pointer to buffer to get root string
  672.       [in]  ULONG cbBufSize,                    // size of buffer passed in
  673.       [out] ULONG *pcbActualSize                // size of actual data returned
  674.     );
  675. }
  676.  
  677.  
  678. //==========================================================================
  679. //==========================================================================
  680. //
  681. // typedefs used by IDvdGraphBuilder interface.
  682. //
  683. //==========================================================================
  684. //==========================================================================
  685.  
  686. typedef enum _AM_DVD_GRAPH_FLAGS {
  687.     AM_DVD_HWDEC_PREFER =  0x01,   // default 
  688.     AM_DVD_HWDEC_ONLY   =  0x02,
  689.     AM_DVD_SWDEC_PREFER =  0x04,
  690.     AM_DVD_SWDEC_ONLY   =  0x08,
  691.     AM_DVD_NOVPE        = 0x100
  692. } AM_DVD_GRAPH_FLAGS ;
  693.  
  694. typedef enum _AM_DVD_STREAM_FLAGS {
  695.     AM_DVD_STREAM_VIDEO  = 0x01,
  696.     AM_DVD_STREAM_AUDIO  = 0x02,
  697.     AM_DVD_STREAM_SUBPIC = 0x04
  698. } AM_DVD_STREAM_FLAGS ;
  699.  
  700. typedef struct {
  701.     HRESULT hrVPEStatus ;         // VPE mixing error code (0 => success)
  702.     BOOL    bDvdVolInvalid ;      // Is specified DVD volume invalid?
  703.     BOOL    bDvdVolUnknown ;      // Is DVD volume to be played not specified/not found?
  704.     BOOL    bNoLine21In ;         // video decoder doesn't produce line21 (CC) data
  705.     BOOL    bNoLine21Out ;        // can't show decoded line21 data as CC on video
  706.     int     iNumStreams ;         // number of DVD streams to render
  707.     int     iNumStreamsFailed ;   // number of streams failed to render
  708.     DWORD   dwFailedStreamsFlag ; // combination of flags to indicate failed streams
  709. } AM_DVD_RENDERSTATUS ;
  710.  
  711.  
  712. // 
  713. // IDvdGraphBuilder interface to build a filter graph for DVD-Video playback.
  714. //
  715.  
  716. [
  717.     object,
  718.     local,
  719.     uuid(FCC152B6-F372-11d0-8E00-00C04FD7C08B),
  720.     pointer_default(unique)
  721. ]
  722. interface IDvdGraphBuilder : IUnknown {
  723.  
  724.     // Returns the IGraphBuilder interface for the filtergraph used by the
  725.     // CDvdGraphBuilder object.
  726.     // Remember to *ppGB->Release() when you're done with it
  727.     HRESULT GetFiltergraph
  728.     ( [out] IGraphBuilder **ppGB
  729.     ) ;
  730.  
  731.     // Gets specific interface pointers in the DVD-Video playback graph to 
  732.     // make DVD-Video playback development easier.
  733.     // It helps get the following interfaces to control playback/show CC/
  734.     // position window/control volume etc:
  735.     // - IDvdControl, IDvdInfo
  736.     // - IAMLine21Decoder
  737.     // - IVideoWindow, IBasicVideo
  738.     // - IBasicAudio
  739.     // This method will return 
  740.     // a) E_INVALIDARG if ppvIF is invalid
  741.     // b) E_NOINTERFACE if riid is an IID we don't know about
  742.     // c) VFW_E_DVD_GRAPHNOTREADY if the graph has not been built through 
  743.     //    RenderDvdVideoVolume() yet.
  744.     // Remember to *ppvIF->Release() when you're done with it
  745.     HRESULT GetDvdInterface
  746.     ( [in] REFIID riid,    // IID of the interface required
  747.       [out] void **ppvIF   // returns pointer to the required interface
  748.     ) ;
  749.  
  750.     // Builds a filter graph according to user specs for playing back a
  751.     // DVD-Video volume.
  752.     // This method returns S_FALSE if
  753.     // 1.  the graph has been either built, but either
  754.     //     a) VPE mixing doesn't work (app didn't use AM_DVD_NOVPE flag)
  755.     //     b) video decoder doesn't produce line21 data
  756.     //     c) line21 data couldn't be rendered (decoding/mixing problem)
  757.     //     d) the call specified an invalid volume path or DVD Nav couldn't
  758.     //        locate any DVD-Video volume to be played.
  759.     // 2.  some streams didn't render (completely), but the others have
  760.     //     been rendered so that the volume can be partially played back.
  761.     // The status is indicated through the fields of the pStatus (out)
  762.     // parameter.
  763.     // About 1(a), the app will have enough info to tell the user that the
  764.     // video won't be visible unless a TV is connected to the NTSC out 
  765.     // port of the DVD decoder (presumably HW in this case).
  766.     // For case 1(b) & (c), the app "can" put up a warning/informative message
  767.     // that closed captioning is not available because of the decoder.
  768.     // 1(d) helps an app to ask the user to insert a DVD-Video disc if none 
  769.     // is specified/available in the drive when playback is started.
  770.     // This method builds the graph even if 
  771.     // - an invalid DVD-Video volume is specified
  772.     // - the caller uses lpwszPathName = NULL to make the DVD Nav to locate
  773.     //   the default volume to be played back, but DVD Nav doesn't find a 
  774.     //   default DVD-Video volume to be played back.
  775.     // An app can later specify the volume using IDvdControl::SetRoot() 
  776.     // method.
  777.     // #2 will help the app indicate to the user that some of the streams
  778.     // can't be played.
  779.     // 
  780.     // The graph is built using filters based on the dwFlags value (to use 
  781.     // HW decoders or SW decoders or a mix of them).
  782.     // The dwFlags value is one of the values in AM_DVD_GRAPH_FLAGS enum
  783.     // type.  The default value is AM_DVD_HWDEC_PREFER. None of the 
  784.     // AM_DVD_HWDEC_xxx or AM_DVD_SWDEC_xxx flags can be mixed. However
  785.     // AM_DVD_NOVPE can be OR-ed with any of the AM_DVD_HWDEC_xxx flags.
  786.     //
  787.     // The method returns S_OK if the playback graph is built successfully
  788.     // with all the streams completely rendered and a valid DVD-Video volume 
  789.     // is specified or a default one has been located.
  790.     //
  791.     // If the dwFlags specify conflicting options, E_INVALIDARG is returned.
  792.     // If the graph building fails, the method returns one of the following 
  793.     // error codes:
  794.     //    VFW_E_DVD_RENDERFAIL, VFW_E_DVD_DECNOTENOUGH
  795.     //
  796.     HRESULT RenderDvdVideoVolume
  797.     ( [in] LPCWSTR lpcwszPathName,  // Can be NULL too
  798.       [in] DWORD dwFlags,           // 0 is the default (use max HW)
  799.       [out] AM_DVD_RENDERSTATUS *pStatus // returns indications of ANY failure
  800.     ) ;
  801. }
  802.