|
|
|
The KSPIN_DESCRIPTOR_EX structure describes the characteristics of a pin type on a given filter type.
typedef struct {
const KSPIN_DISPATCH* Dispatch;
const KSAUTOMATION_TABLE* AutomationTable;
KSPIN_DESCRIPTOR PinDescriptor;
ULONG Flags;
ULONG InstancesPossible;
ULONG InstancesNecessary;
const KSALLOCATOR_FRAMING_EX* AllocatorFraming;
PFNKSINTERSECTHANDLEREX IntersectHandler;
} KSPIN_DESCRIPTOR_EX, *PKSPIN_DESCRIPTOR_EX;
| Flag | Description |
|---|---|
| KSPIN_FLAG_DISPATCH_LEVEL_PROCESSING | Indicates that the minidriver requests that the process dispatch to happen at IRQL DISPATCH_LEVEL instead of PASSIVE_LEVEL. |
| KSPIN_FLAG_CRITICAL_PROCESSING | If asynchronous processing has been specified or if passive level processing is demanded and a process call comes in at dispatch level, processing is done in a queued work item. This flag indicates that the work item should be placed on the critical work queue as opposed to the delayed work queue. |
| KSPIN_FLAG_HYPERCRITICAL_PROCESSING | If asynchronous processing has been specified or if passive level processing is demanded and a process call comes in at dispatch level, processing is done in a queued work item. This flag indicates that the work item should be placed on the hypercritical work queue as opposed to the delayed work queue or critical work queue. |
| KSPIN_FLAG_ASYNCHRONOUS_PROCESSING | Indicates that the pin should process data asynchronously. If this flag is set, AVStream does not wait for one process dispatch to be called before proceeding with additional frames. |
| KSPIN_FLAG_DO_NOT_INITIATE_PROCESSING | Indicates that the processing should never be initiated; the process dispatch provided in the dispatch table is never called. This is useful for clients that intend to directly poll the queue at, for example, DPC time to transport data to hardware. |
| KSPIN_FLAG_INITIATE_PROCESSING_ON_EVERY_ARRIVAL | Indicates that processing should occur every time a data frame arrives into the queue. Without specifying this flag of KSPIN_FLAG_DO_NOT_INITIATE_PROCESSING, the process dispatch is only called when data arrives into a previously empty queue. |
| KSPIN_FLAG_FRAMES_NOT_REQUIRED_FOR_PROCESSING | Indicates that frames are not required on this pin for processing to commence. This flag is useful only for filter-centric filters. Pins that do not specify this flag delay processing on the filter if they do not have available frames. Pins that do specify this flag do not delay processing in this manner. If a pin specifies this flag, it becomes the responsibility of the process dispatch to check for available frames. |
| KSPIN_FLAG_ENFORCE_FIFO | Specifying this flag causes the queue to force IRPs to be handled in a first-in-first-out manner. If one IRP is completed by the minidriver prior to an IRP that was sent earlier, the later IRP is not completed by AVStream until the earlier IRP has been completed by the minidriver. |
| KSPIN_FLAG_GENERATE_MAPPINGS | Indicates that scatter/gather mappings should be generated for devices that use scatter/gather DMA to transport data from the pin to hardware. Clients that intend to use this feature need to register their DMA adapter object with AVStream via the KsDeviceRegisterAdapterObject function. |
| KSPIN_FLAG_DISTINCT_TRAILING_EDGE | Indicates that the queue associated with the pin should have a trailing edge stream pointer. The trailing edge pointer is a special stream pointer that points to the oldest data in the queue unless clone pointers exist on older data. Any data frames in the window between the leading and trailing edge stream pointers are considered to have at least one reference count on them and are not completed until they move out of the window by advancing the trailing edge with KsPinGetTrailingEdgeStreamPointer and one of the KsStreamPointerAdvance* or KsStreamPointerUnlock functions. Pins that do not specify this flag do not have a trailing edge stream pointer. |
| KSPIN_FLAG_PROCESS_IN_RUN_STATE_ONLY | Indicates that this pin only processes data while in KSSTATE_RUN. Pins that specify this flag are never called upon to process while not in KSSTATE_RUN. Further, any pin that specifies this flag and is part of a filter-centric filter causes the filter not to process if the given pin is not in KSSTATE_RUN. |
| KSPIN_FLAG_SPLITTER | Indicates that this pin (an output pin) is a splitter. Pins that specify this flag should indicate a number of possible instances greater than one. When a second instance of this pin is created, AVStream automatically sets up a splitter so that frames sent to the original pin are copied to the new pin. Note that this copying is done automatically by AVStream. Clients typically can ignore process pins that have nonNULL DelegateBranch and CopySource pointers. These members indicate that the pin is part of a splitter branch and is handled automatically by AVStream. In releases post-DirectX 8.0, this flag works for pins on both filter-centric and pin-centric filters. Older releases support this flag only for pins on filter-centric filters. |
| KSPIN_FLAG_USE_STANDARD_TRANSPORT | This flag forces the pin to use the standard transport mechanism. It overrides all other checks (communication type, medium type, interface type, etc.) on the pin. Specifying both this flag and KSPIN_FLAG_DO_NOT_USE_STANDARD_TRANSPORT results in the standard transport being used. This flag overrides all other checks. |
| KSPIN_FLAG_DO_NOT_USE_STANDARD_TRANSPORT | Indicates that the pin does not use the standard transport mechanism. Pins that do not use the standard transport mechanism will not belong to a pipe section and will not have associated queues. |
| KSPIN_FLAG_FIXED_FORMAT | Indicates that this pin uses a fixed data format. Any attempt to set the data format returns STATUS_INVALID_DEVICE_REQUEST. |
| KSPIN_FLAG_GENERATE_EOS_EVENTS | Indicates that this pin handles connection event support requests. |
| KSPIN_FLAG_RENDERER | Specifies that this pin is capable of rendering frames. |
| KSPIN_FLAG_SOME_FRAMES_REQUIRED_FOR_PROCESSING | When specified on a filter-centric filter pin, indicates that one or more instances of the pin type in question must have frames available in order to process data. Mutually exclusive with KSPIN_FLAG_FRAMES_NOT_REQUIRED_FOR_PROCESSING.
Note that this behavior can be obtained through KsPinAttachOrGate by manually setting up an OR gate as the frame gate for every instance of the pin and attaching this OR gate to the filter's AND gate. When using this flag, minidrivers cannot call KsPinAttachAndGate or KsPinAttachOrGate on the associated pin instances. (The flag effectively does this for you for the simple OR case.) Also see Filter-Centric Processing. |
| KSPIN_FLAG_PROCESS_IF_ANY_IN_RUN_STATE | When specified on a filter-centric pin, indicates that processing may occur when one or more of the pin instances so flagged are in the run state. Note that all non-stopped pins still must be in at least pause to process data. The default behavior is to process in pause; KSPIN_FLAG_PROCESS_IN_RUN_STATE_ONLY allows this behavior to be changed to processing in run when all of the pin instances are in run. Also see Filter-Centric Processing. |
| KSPIN_FLAG_IMPLEMENT_CLOCK | Indicates that this pin exposes a clock that can be selected by the graph manager as a master clock. |
Declared in ks.h. Include ks.h.
This structure is available in Windows XP and later operating systems and in DirectX 8.0 and later versions.
Note that the allocator framing requirements of your pin may be ignored despite the fact that your allocator framing specifies that alignment or size is absolutely required to be a certain value. If your kernel-mode driver is connected to an upstream user-mode filter that allocates for it and the particular upstream filter’s allocator does not understand framing requirements, this can happen (current particular examples include the MPEG-2 splitter).
Further, if you specify KSPIN_FLAG_DO_NOT_INITIATE_PROCESSING and the pin uses the standard transport mechanism, you must have a processing object. This means there must be some process dispatch provided (either at the filter level or at the pin level); even if this function is never called, it must be provided in this circumstance.
Data Range Intersections in AVStream and Avstream Splitters.
KSPIN_DISPATCH, KSPIN_DESCRIPTOR, KSALLOCATOR_FRAMING_EX, KsDeviceRegisterAdapterObject