home *** CD-ROM | disk | FTP | other *** search
/ Beginning Direct3D Game Programming / Direct3D.iso / directx / dxf / include / dshowidl / mediaobj.idl < prev    next >
Text File  |  2000-10-01  |  13KB  |  413 lines
  1. //------------------------------------------------------------------------------
  2. // File: MediaObj.idl
  3. //
  4. // Desc: Define the interfaces for DirectX Media Objects.  This file will
  5. //       be processed by the MIDL tool to produce mediaobj.h and proxy-stub
  6. //       code.
  7. //
  8. // Copyright (c) 1999 - 2000, Microsoft Corporation.  All rights reserved.
  9. //------------------------------------------------------------------------------
  10.  
  11.  
  12. import "unknwn.idl";
  13. import "objidl.idl";
  14.  
  15. //  DMO_MEDIA_TYPE structure
  16.  
  17. cpp_quote("#ifdef __strmif_h__")
  18. cpp_quote("typedef AM_MEDIA_TYPE DMO_MEDIA_TYPE;")
  19. cpp_quote("#else")
  20. typedef struct _DMOMediaType {
  21.     GUID     majortype;
  22.     GUID     subtype;
  23.     BOOL     bFixedSizeSamples;
  24.     BOOL     bTemporalCompression;
  25.     ULONG    lSampleSize;
  26.     GUID     formattype;
  27.     IUnknown *pUnk;
  28.     ULONG    cbFormat;
  29.     [size_is(cbFormat)] BYTE * pbFormat;
  30. } DMO_MEDIA_TYPE;
  31. typedef LONGLONG REFERENCE_TIME;
  32. cpp_quote("#endif")
  33.  
  34.  
  35. // Per-buffer flags that apply to input buffers
  36. enum _DMO_INPUT_DATA_BUFFER_FLAGS {
  37.     DMO_INPUT_DATA_BUFFERF_SYNCPOINT       = 0x00000001,
  38.     DMO_INPUT_DATA_BUFFERF_TIME            = 0x00000002,
  39.     DMO_INPUT_DATA_BUFFERF_TIMELENGTH      = 0x00000004
  40. };
  41.  
  42. // Per-buffer flags that apply to output buffers.
  43. enum _DMO_OUTPUT_DATA_BUFFER_FLAGS {
  44.     DMO_OUTPUT_DATA_BUFFERF_SYNCPOINT       = 0x00000001,
  45.     DMO_OUTPUT_DATA_BUFFERF_TIME            = 0x00000002,
  46.     DMO_OUTPUT_DATA_BUFFERF_TIMELENGTH      = 0x00000004,
  47.  
  48.     //
  49.     // This flag means the object could have generated more data for this
  50.     // output stream, even with no additional input from any input stream,
  51.     // but the output buffer did not have sufficient room.
  52.     //
  53.     DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE      = 0x01000000
  54. };
  55.  
  56. // Flags returned by GetInputStatus()
  57. enum _DMO_INPUT_STATUS_FLAGS {
  58.     //
  59.     // ACCEPT_DATA indicates that the input stream is ready to accept
  60.     // new data via ProcessInput().
  61.     //
  62.     DMO_INPUT_STATUSF_ACCEPT_DATA   = 0x00000001
  63. };
  64.  
  65. // Flags returned by GetInputStreamInfo()
  66. enum _DMO_INPUT_STREAM_INFO_FLAGS {
  67.     DMO_INPUT_STREAMF_WHOLE_SAMPLES            = 0x00000001,
  68.     DMO_INPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER = 0x00000002,
  69.     DMO_INPUT_STREAMF_FIXED_SAMPLE_SIZE        = 0x00000004,
  70.     DMO_INPUT_STREAMF_HOLDS_BUFFERS            = 0x00000008
  71. };
  72.  
  73. // Flags returned by GetOutputStreamInfo()
  74. enum _DMO_OUTPUT_STREAM_INFO_FLAGS {
  75.     DMO_OUTPUT_STREAMF_WHOLE_SAMPLES            = 0x00000001,
  76.     DMO_OUTPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER = 0x00000002,
  77.     DMO_OUTPUT_STREAMF_FIXED_SAMPLE_SIZE        = 0x00000004,
  78.     DMO_OUTPUT_STREAMF_DISCARDABLE              = 0x00000008,
  79.     DMO_OUTPUT_STREAMF_OPTIONAL                 = 0x00000010
  80. };
  81.  
  82. //  SetType flags
  83. enum _DMO_SET_TYPE_FLAGS {
  84.     DMO_SET_TYPEF_TEST_ONLY   = 0x00000001,// check but don't set
  85.     DMO_SET_TYPEF_CLEAR       = 0x00000002 // unset
  86. };
  87.  
  88. //  Process Output Flags
  89. enum _DMO_PROCESS_OUTPUT_FLAGS {
  90.     DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER = 0x00000001 //  Discard
  91. };
  92.  
  93. // Buffer wrapper interface
  94. [
  95.     object,
  96.     uuid(59eff8b9-938c-4a26-82f2-95cb84cdc837)
  97. ]
  98. interface IMediaBuffer : IUnknown
  99. {
  100.     HRESULT SetLength(
  101.        DWORD cbLength
  102.     );
  103.     HRESULT GetMaxLength(
  104.        [out] DWORD *pcbMaxLength
  105.     );
  106.     HRESULT GetBufferAndLength(
  107.        [out] BYTE **ppBuffer,  // not filled if NULL
  108.        [out] DWORD *pcbLength // not filled if NULL
  109.     );
  110. }
  111.  
  112. //
  113. // Output buffer info structure: one of these must be passed in for each
  114. // output stream with every ProcessOutput() call
  115. // All [out] fields should be
  116. // assumed undefined if ProcessOutput() failed
  117. //
  118. typedef struct _DMO_OUTPUT_DATA_BUFFER {
  119.  
  120.     IMediaBuffer *pBuffer; // [in] can be NULL
  121.  
  122.     // ProcessOutput() must set any appropriate flags and zero out the rest.
  123.     DWORD dwStatus; // [out] DMO_OUTPUT_DATA_BUFFERF_XXX (INCOMPLETE, etc.)
  124.  
  125.     //
  126.     // Each of these is valid if the corresponding flag is set in dwStatus
  127.     //
  128.     REFERENCE_TIME rtTimestamp; // [out]
  129.     REFERENCE_TIME rtTimelength; // [out]
  130. } DMO_OUTPUT_DATA_BUFFER, *PDMO_OUTPUT_DATA_BUFFER;
  131.  
  132.  
  133. //  Interface supported by media objects
  134. [
  135.     object,
  136.     uuid(d8ad0f58-5494-4102-97c5-ec798e59bcf4)
  137. ]
  138. interface IMediaObject : IUnknown
  139. {
  140.  
  141. //
  142. // Stream enumeration
  143. //
  144.         HRESULT GetStreamCount(
  145.                 [out] DWORD *pcInputStreams,
  146.                 [out] DWORD *pcOutputStreams
  147.         );
  148.         HRESULT GetInputStreamInfo(
  149.                 DWORD dwInputStreamIndex, // 0-based
  150.                 [out] DWORD *pdwFlags // HOLDS_BUFFERS
  151.         );
  152.         HRESULT GetOutputStreamInfo(
  153.                 DWORD dwOutputStreamIndex, // 0-based
  154.                 [out] DWORD *pdwFlags      // Media object sets to 0
  155.         );
  156.  
  157. //
  158. // Mediatypes
  159. //
  160.         //
  161.         // GetType - iterate through media types supported by a stream.
  162.         // Returns S_FALSE if the type index is out of range ("no more types").
  163.         //
  164.         HRESULT GetInputType(
  165.                 DWORD dwInputStreamIndex,
  166.                 DWORD dwTypeIndex, // 0-based
  167.                 [out] DMO_MEDIA_TYPE *pmt
  168.         );
  169.         HRESULT GetOutputType(
  170.                 DWORD dwOutputStreamIndex,
  171.                 DWORD dwTypeIndex, // 0-based
  172.                 [out] DMO_MEDIA_TYPE *pmt
  173.         );
  174.  
  175.         //
  176.         // SetType - tell the object the type of data it will work with.
  177.         //
  178.         HRESULT SetInputType(
  179.                 DWORD dwInputStreamIndex,
  180.                 [in] const DMO_MEDIA_TYPE *pmt,
  181.                 DWORD dwFlags // test only
  182.         );
  183.         HRESULT SetOutputType(
  184.                 DWORD dwOutputStreamIndex,
  185.                 [in]  const DMO_MEDIA_TYPE *pmt,
  186.                 DWORD dwFlags // test only
  187.         );
  188.  
  189.         //
  190.         // GetCurrentType - get the last mediatype supplied via SetType.
  191.         // Returns S_FALSE if SetType has not been called.
  192.         //
  193.         HRESULT GetInputCurrentType(
  194.                 DWORD dwInputStreamIndex,
  195.                 [out] DMO_MEDIA_TYPE *pmt
  196.         );
  197.         HRESULT GetOutputCurrentType(
  198.                 DWORD dwOutputStreamIndex,
  199.                 [out] DMO_MEDIA_TYPE *pmt
  200.         );
  201.  
  202. //
  203. // SizeInfo
  204. //
  205.         //
  206.         // GetSizeInfo - Get buffer size requirementes of a stream.
  207.         //
  208.         // If buffer size depends on the media type used, the object should
  209.         // base its response on the most recent media type set for this stream.
  210.         // If no mediatype has been set, the object may return an error.
  211.         //
  212.         HRESULT GetInputSizeInfo(
  213.                 DWORD dwInputStreamIndex,
  214.                 [out] DWORD *pcbSize, // size of input 'quantum'
  215.                 [out] DWORD *pcbMaxLookahead, // max total bytes held
  216.                 [out] DWORD *pcbAlignment  // buffer alignment requirement
  217.         );
  218.         HRESULT GetOutputSizeInfo(
  219.                 DWORD dwOutputStreamIndex,
  220.                 [out] DWORD *pcbSize, // size of output 'quantum'
  221.                 [out] DWORD *pcbAlignment  // buffer alignment requirement
  222.         );
  223.  
  224. //
  225. // Latency methods
  226. //
  227.         HRESULT GetInputMaxLatency(
  228.                 DWORD dwInputStreamIndex,
  229.                 [out] REFERENCE_TIME *prtMaxLatency
  230.         );
  231.         HRESULT SetInputMaxLatency(
  232.                 DWORD dwInputStreamIndex,
  233.                 REFERENCE_TIME rtMaxLatency
  234.         );
  235.  
  236. //
  237. // Streaming / state methods
  238. //
  239.         //
  240.         // Flush() - discard any buffered data.
  241.         //
  242.         HRESULT Flush();
  243.  
  244.         //
  245.         // Send a discontinuity to an input stream.  The object will not
  246.         // accept any more data on this input stream until the discontinuity
  247.         // has been completely processed, which may involve multiple
  248.         // ProcessOutput() calls.
  249.         //
  250.         HRESULT Discontinuity(DWORD dwInputStreamIndex);
  251.  
  252.         //
  253.         // If a streaming object needs to perform any time consuming
  254.         // initialization before it can stream data, it should do it inside
  255.         // AllocateStreamingResources() rather than during the first process
  256.         // call.
  257.         //
  258.         // This method is NOT guaranteed to be called before streaming
  259.         // starts.  If it is not called, the object should perform any
  260.         // required initialization during a process call.
  261.         //
  262.         HRESULT AllocateStreamingResources();
  263.  
  264.         // Free anything allocated in AllocateStreamingResources().
  265.         HRESULT FreeStreamingResources();
  266.  
  267.         // GetInputStatus - the only flag defined right now is ACCEPT_DATA.
  268.         HRESULT GetInputStatus(
  269.                 DWORD dwInputStreamIndex,
  270.                 [out] DWORD *dwFlags // ACCEPT_DATA
  271.         );
  272.  
  273.         //
  274.         // Pass one new buffer to an input stream
  275.         //
  276.         HRESULT ProcessInput(
  277.                 DWORD dwInputStreamIndex,
  278.                 IMediaBuffer *pBuffer, // must not be NULL
  279.                 DWORD dwFlags, // DMO_INPUT_DATA_BUFFERF_XXX (syncpoint, etc.)
  280.                 REFERENCE_TIME rtTimestamp, // valid if flag set
  281.                 REFERENCE_TIME rtTimelength // valid if flag set
  282.         );
  283.  
  284.         //
  285.         // ProcessOutput() - generate output for current input buffers
  286.         //
  287.         // Output stream specific status information is returned in the
  288.         // dwStatus member of each buffer wrapper structure.
  289.         //
  290.         HRESULT ProcessOutput(
  291.                 DWORD dwFlags, // DMO_PROCESS_OUTPUT_FLAGS
  292.                 DWORD cOutputBufferCount, // # returned by GetStreamCount()
  293.         [in,out,size_is(cOutputBufferCount)]
  294.                    DMO_OUTPUT_DATA_BUFFER *pOutputBuffers, // one per stream
  295.         [out] DWORD *pdwStatus  // TBD, must be set to 0
  296.     );
  297.  
  298.         //  Locking - lock if bLock is TRUE, otherwise unlock
  299.         HRESULT Lock(LONG bLock);
  300. };
  301.  
  302.  
  303. //
  304. // Interface returned by the DMO enumeration API
  305. //
  306. [
  307. object,
  308. uuid(2c3cd98a-2bfa-4a53-9c27-5249ba64ba0f)
  309. ]
  310. interface IEnumDMO : IUnknown {
  311.     HRESULT Next(
  312.         DWORD cItemsToFetch,
  313.         [out, size_is(cItemsToFetch), length_is(*pcItemsFetched)] CLSID *pCLSID,
  314.         [out, size_is(cItemsToFetch), length_is(*pcItemsFetched), string] WCHAR **Names,
  315.         [out] DWORD *pcItemsFetched
  316.     );
  317.     HRESULT Skip(
  318.         DWORD cItemsToSkip
  319.     );
  320.     HRESULT Reset(void);
  321.     HRESULT Clone(
  322.         [out] IEnumDMO **ppEnum
  323.     );
  324. }
  325.  
  326.  
  327. // Flags for IMediaObjectInPlace::Process
  328. enum _DMO_INPLACE_PROCESS_FLAGS {
  329.     DMO_INPLACE_NORMAL = 0x00000000,
  330.     DMO_INPLACE_ZERO   = 0x00000001
  331. };
  332.  
  333. [
  334. object,
  335. uuid(651b9ad0-0fc7-4aa9-9538-d89931010741)
  336. ]
  337. interface IMediaObjectInPlace : IUnknown {
  338.  
  339.     // Proces - Given a buffer of size ulSize, put the output
  340.     // of the DMO into the same buffer.
  341.     HRESULT Process(
  342.         [in] ULONG ulSize,
  343.         [in,out,size_is(ulSize)] BYTE* pData,
  344.         [in] REFERENCE_TIME refTimeStart,
  345.         [in] DWORD dwFlags
  346.     );
  347.  
  348.     // Create a copy of the In-Place Media Object. This allows
  349.     // for very fast initialization of a number of In-Place objects
  350.     // in a known state.
  351.     HRESULT Clone(
  352.             [out] IMediaObjectInPlace **ppMediaObject
  353.     );
  354.  
  355.     // GetLatency - Returns a REFERENCE_TIME value
  356.     // (1 tick = 100ns) which corresponds to the latency time
  357.     // processing this effect will add to the graph. This assumes
  358.     // the effect cost per buffer is a constant.
  359.     HRESULT GetLatency(
  360.         [out] REFERENCE_TIME *pLatencyTime
  361.     );
  362. }
  363.  
  364. // Quality control status flags
  365. enum _DMO_QUALITY_STATUS_FLAGS {
  366.     DMO_QUALITY_STATUS_ENABLED = 0x00000001
  367. };
  368.  
  369. [
  370. object,
  371. uuid(65abea96-cf36-453f-af8a-705e98f16260)
  372. ]
  373. interface IDMOQualityControl : IUnknown {
  374.     HRESULT SetNow(
  375.         [in] REFERENCE_TIME rtNow
  376.     );
  377.     HRESULT SetStatus(
  378.         [in] DWORD dwFlags
  379.     );
  380.     HRESULT GetStatus(
  381.         [out] DWORD *pdwFlags
  382.     );
  383. }
  384.  
  385. // Flags for IVideoOutputOptimizations
  386. enum _DMO_VIDEO_OUTPUT_STREAM_FLAGS {
  387.     DMO_VOSF_NEEDS_PREVIOUS_SAMPLE = 0x00000001
  388. };
  389.  
  390. [
  391. object,
  392. uuid(be8f4f4e-5b16-4d29-b350-7f6b5d9298ac)
  393. ]
  394. interface IDMOVideoOutputOptimizations : IUnknown {
  395.     HRESULT QueryOperationModePreferences (
  396.         ULONG ulOutputStreamIndex,
  397.         DWORD *pdwRequestedCapabilities
  398.     );
  399.     HRESULT SetOperationMode (
  400.         ULONG ulOutputStreamIndex,
  401.         DWORD dwEnabledFeatures
  402.     );
  403.     HRESULT GetCurrentOperationMode (
  404.         ULONG ulOutputStreamIndex,
  405.         DWORD *pdwEnabledFeatures
  406.     );
  407.     HRESULT GetCurrentSampleRequirements (
  408.         ULONG ulOutputStreamIndex,
  409.         DWORD *pdwRequestedFeatures
  410.     );
  411. }
  412.  
  413.