NVIDIA DRIVE OS Linux SDK API Reference

5.2.0 Release
For Test and Development only

Detailed Description

The NvSciStream library is a layer on top of NvSciBuf and NvSciSync libraries that provides utilities for streaming sequences of data packets between multiple application modules to support a wide variety of use cases.

Functions

NvSciError NvSciStreamBlockConnect (NvSciStreamBlock const upstream, NvSciStreamBlock const downstream)
 Connects two stream blocks. More...
 
NvSciError NvSciStreamProducerCreate (NvSciStreamBlock const pool, NvSciStreamBlock *const producer)
 Creates a stream producer block. More...
 
NvSciError NvSciStreamConsumerCreate (NvSciStreamBlock const queue, NvSciStreamBlock *const consumer)
 Creates a stream consumer block. More...
 
NvSciError NvSciStreamStaticPoolCreate (uint32_t const numPackets, NvSciStreamBlock *const pool)
 Creates a static stream pool block. More...
 
NvSciError NvSciStreamMailboxQueueCreate (NvSciStreamBlock *const queue)
 Creates a mailbox queue block. More...
 
NvSciError NvSciStreamFifoQueueCreate (NvSciStreamBlock *const queue)
 Creates a FIFO queue block. More...
 
NvSciError NvSciStreamMulticastCreate (uint32_t const outputCount, NvSciStreamBlock *const multicast)
 Creates a multicast block. More...
 
NvSciError NvSciStreamIpcSrcCreate (NvSciIpcEndpoint const ipcEndpoint, NvSciSyncModule const syncModule, NvSciBufModule const bufModule, NvSciStreamBlock *const ipc)
 Creates an IPC source block. More...
 
NvSciError NvSciStreamIpcDstCreate (NvSciIpcEndpoint const ipcEndpoint, NvSciSyncModule const syncModule, NvSciBufModule const bufModule, NvSciStreamBlock *const ipc)
 Creates an IPC destination block. More...
 
NvSciError NvSciStreamBlockEventQuery (NvSciStreamBlock const block, int64_t const timeoutUsec, NvSciStreamEvent *const event)
 Queries for the next event from block's event queue, optionally waiting, and returns it to the caller. More...
 
NvSciError NvSciStreamBlockSyncRequirements (NvSciStreamBlock const block, bool const synchronousOnly, NvSciSyncAttrList const waitSyncAttrList)
 Sets block sync object requirements. More...
 
NvSciError NvSciStreamBlockSyncObjCount (NvSciStreamBlock const block, uint32_t const count)
 Provides block's number of sync objects. More...
 
NvSciError NvSciStreamBlockSyncObject (NvSciStreamBlock const block, uint32_t const index, NvSciSyncObj const syncObj)
 Provides block's sync object. More...
 
NvSciError NvSciStreamBlockPacketElementCount (NvSciStreamBlock const block, uint32_t const count)
 Block sets the number of elements in a packet. More...
 
NvSciError NvSciStreamBlockPacketAttr (NvSciStreamBlock const block, uint32_t const index, uint32_t const type, NvSciStreamElementMode const syncMode, NvSciBufAttrList const bufAttrList)
 Sets block packet requirements/capabilities. More...
 
NvSciError NvSciStreamPoolPacketCreate (NvSciStreamBlock const pool, NvSciStreamCookie const cookie, NvSciStreamPacket *const handle)
 Adds a new packet to the pool. More...
 
NvSciError NvSciStreamPoolPacketInsertBuffer (NvSciStreamBlock const pool, NvSciStreamPacket const handle, uint32_t const index, NvSciBufObj const bufObj)
 Registers a buffer to the packet. More...
 
NvSciError NvSciStreamPoolPacketDelete (NvSciStreamBlock const pool, NvSciStreamPacket const handle)
 Removes a packet from the pool. More...
 
NvSciError NvSciStreamBlockPacketAccept (NvSciStreamBlock const block, NvSciStreamPacket const handle, NvSciStreamCookie const cookie, NvSciError const err)
 Accepts a packet provided by the pool. More...
 
NvSciError NvSciStreamBlockElementAccept (NvSciStreamBlock const block, NvSciStreamPacket const handle, uint32_t const index, NvSciError const err)
 Accepts a packet element provided by the pool. More...
 
NvSciError NvSciStreamProducerPacketGet (NvSciStreamBlock const producer, NvSciStreamCookie *const cookie, NvSciSyncFence *const prefences)
 Instructs the producer to get a packet from the pool. More...
 
NvSciError NvSciStreamProducerPacketPresent (NvSciStreamBlock const producer, NvSciStreamPacket const handle, NvSciSyncFence const *const postfences)
 Inserts a data packet into the stream. More...
 
NvSciError NvSciStreamConsumerPacketAcquire (NvSciStreamBlock const consumer, NvSciStreamCookie *const cookie, NvSciSyncFence *const prefences)
 Instructs the consumer to get a packet from the queue. More...
 
NvSciError NvSciStreamConsumerPacketRelease (NvSciStreamBlock const consumer, NvSciStreamPacket const handle, NvSciSyncFence const *const postfences)
 Returns a data packet to the stream. More...
 
NvSciError NvSciStreamBlockDelete (NvSciStreamBlock const block)
 Destroys a stream block. More...
 
NvSciError NvSciStreamAttributeQuery (NvSciStreamQueryableAttrib const attr, int32_t *const value)
 Queries NvSciStream attributes. More...
 

Function Documentation

◆ NvSciStreamAttributeQuery()

NvSciError NvSciStreamAttributeQuery ( NvSciStreamQueryableAttrib const  attr,
int32_t *const  value 
)

Queries NvSciStream attributes.

Queries the value of one of the queryable NvSciStream attributes.

Preconditions

None.

Actions

  • NvSciStream looks up the value of the attribute.

Postconditions

None changed.

Parameters
[in]attrThe attribute to query.
[out]valueThe value queried.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamBlockConnect()

NvSciError NvSciStreamBlockConnect ( NvSciStreamBlock const  upstream,
NvSciStreamBlock const  downstream 
)

Connects two stream blocks.

Connects an available output of one block with an available input of another block.

Each input and output can only have one connection. A stream is fully connected when all inputs and outputs of all blocks in the stream have a connection.

Preconditions

  • The upstream block has an available output connection.
  • The downstream block has an available input connection.

Actions

  • Establish a connection between the two blocks.

Postconditions

  • When the block has a complete chain of connections to the producer, it will receive a ConnectUpstream event.
  • When the block has a complete chain of connections to all consumers, it will receive a ConnectDownstream event.
Parameters
[in]upstreamHandle of the upstream block.
[in]downstreamHandle of the downstream block.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamBlockDelete()

NvSciError NvSciStreamBlockDelete ( NvSciStreamBlock const  block)

Destroys a stream block.

Schedules a stream block for destruction, disconnecting the stream if this hasn't already occurred.

The block's handle may no longer be used for any function calls, and may be reassigned to a new block if more are created.

Resources associated with the block may not be freed immediately.

Any pending data packets downstream of the destroyed block will still be available for the consumer to acquire.

No new packets upstream of the destroyed block can be presented. Once packets are released, they will be freed.

Preconditions

None.

Actions

  • The block is scheduled for destruction.
  • A DisconnectUpstream event is sent to all upstream blocks, if they haven't received one already.
  • A DisconnectDownstream event is sent to all downstream blocks, if they haven't received one already.

Postconditions

  • The block handle is no longer valid.
Parameters
[in]blockBlock handle.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamBlockElementAccept()

NvSciError NvSciStreamBlockElementAccept ( NvSciStreamBlock const  block,
NvSciStreamPacket const  handle,
uint32_t const  index,
NvSciError const  err 
)

Accepts a packet element provided by the pool.

Upon receiving a PacketElement event, the producer and consumer should map the buffers into their space and report the status by calling this function.

If successfully mapped, the error value should be NvSciError_Success. Otherwise it should be an error code indicating what failed.

Preconditions

  • The packet handle has been received in a previous PacketCreate event, and the indexed element has been received in a previous PacketElement event.

Actions

  • Sends a ElementStatus event to the pool.

Postconditions

  • If successful, the element buffers may now be used to send/receive data.
Parameters
[in]blockProducer or consumer block handle.
[in]handlePacket handle.
[in]indexIndex of the element within the packet.
[in]errStatus of mapping operation.
Returns
status code
  • NvSciError_Success: Element successfully mapped.
  • NvSciError_BadParameter: block refers to an invalid instance, or handle does not match any packet in the block, or index is not valid.
  • NvSciError_NotImplemented: block is not a producer or consumer block.
  • NvSciError_StreamNotConnected: Stream is not fully connected.
  • NvSciError_NotPermitted: block is in safety mode. Operation not allowed.
  • NvSciError_InvalidState: Element is not in a state to be accepted (already accepted).
  • NvSciError_InsufficientMemory: Memory not enough for allocation or for ipc-related operations.
  • NvSciError_StreamInternalError: An internal system error occurred, such as a mutex-locking failure.

◆ NvSciStreamBlockEventQuery()

NvSciError NvSciStreamBlockEventQuery ( NvSciStreamBlock const  block,
int64_t const  timeoutUsec,
NvSciStreamEvent *const  event 
)

Queries for the next event from block's event queue, optionally waiting, and returns it to the caller.

The appropriate handling of each type of event is described in the section for the corresponding event structure.

Preconditions

  • The block to query has been created.

Actions

  • Wait until an event is pending on the block or the specified timeout period is reached, whichever comes first.
  • Remove the next event (if any) from the block's event queue, fill in the event data structure.

Postconditions

  • As defined for each event type, dequeuing an event may allow other operations on the block to proceed.
Parameters
[in]blockBlock handle.
[in]timeoutUsecTimeout in microseconds (-1 to wait forever).
[out]eventEvent and the corresponding event data.
Returns
NvSciError, the completion code of this operation.
  • NvSciError_Success event is filled with the queried event data.
  • NvSciError_Timeout The timeoutUsec period was reached before an event became available.
  • NvSciError_BadParameter event is null or block is invalid.
  • NvSciError_StreamInternalError An internal system error occurred, such as a mutex-locking failure.

    On safety-critical systems, this function never generates this error. A system-wide mechanism shall be notified and intervene when such error occurs.

◆ NvSciStreamBlockPacketAccept()

NvSciError NvSciStreamBlockPacketAccept ( NvSciStreamBlock const  block,
NvSciStreamPacket const  handle,
NvSciStreamCookie const  cookie,
NvSciError const  err 
)

Accepts a packet provided by the pool.

Upon receiving a PacketCreate event, the producer and consumer should set up their own internal data structures for the packet and assign a cookie which they will use to look up the data structure. Afterwards, they should then call this function.

If the client setup is successful, the error value should be set to NvSciError_Success, and the cookie assigned to the packet should be provided. NvSciStream will track the cookie with the packet and use it for all subsequent events related to the packet.

If the client setup is not successful, an error value should be provided to indicate what went wrong. The cookie is ignored.

Preconditions

  • The packet handle has been received in a previous PacketCreate event, and has not yet been accepted.

Actions

  • Sends a PacketStatus event to the pool.

Postconditions

  • If successful, the packet elements may now be received.
Parameters
[in]blockProducer or consumer block handle.
[in]handlePacket handle.
[in]cookieBlock's cookie for the packet handle.
[in]errStatus of packet structure setup.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamBlockPacketAttr()

NvSciError NvSciStreamBlockPacketAttr ( NvSciStreamBlock const  block,
uint32_t const  index,
uint32_t const  type,
NvSciStreamElementMode const  syncMode,
NvSciBufAttrList const  bufAttrList 
)

Sets block packet requirements/capabilities.

Used with the consumer to indicate what packet elements it desires, the producer to indicate what packet elements it can provide, and the pool to establish the combined packet element list.

For safety-critical platforms, this function is called only once per packet element at setup time. The packet attributes are immutable during streaming.

For non-safety platforms, the producer may call it again during streaming to modify portions of the memory attributes, such as changing the dimensions or image format of some elements.

It may not modify the types of elements. The pool application is expected to respond by updating the complete packet attribute set, deleting the old packets, and creating new ones.

Preconditions

  • For producer and consumer, must have received appropriate Connect event from the other endpoint(s).
  • For pool, must have received PacketAttrProducer and PacketAttrConsumer events.
  • If element count is already set to zero by NvSciStreamBlockPacketElementCount, this call will fail.

Actions

  • Send packet attributes to block.
  • For producer when the attributes for the last element are sent, PacketAttrProducer events (one per element) and a PacketElementCountProducer event will be sent to pool.
  • For consumer when the attributes for the last element are sent, PacketAttrConsumer events (one per element) and a PacketElementCountConsumer event will be sent to pool.
  • For pool, when the attributes for the last element are sent, PacketAttr events (one per element), and a PacketElementCount event will be sent to consumer and producer.

Postconditions

  • For the pool, packets may now be created.
Parameters
[in]blockBlock handle.
[in]indexIndex of element within list
[in]typeUser-defined type to identify element
[in]syncModePrefered access mode for element data
[in]bufAttrListAttributes for element buffer
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamBlockPacketElementCount()

NvSciError NvSciStreamBlockPacketElementCount ( NvSciStreamBlock const  block,
uint32_t const  count 
)

Block sets the number of elements in a packet.

Used with the consumer to indicate the number of packet elements it desires, the producer to indicate the number of packet elements it can provide, and the pool to determine the combined number of packet elements.

The element count is implicitly set to one.

If the block needs or provides no element, the application must make this call with count equal to zero.

The number of packet elements is immutable during streaming.

Preconditions

  • For producer and consumer, must have received appropriate Connect event from the other endpoint(s).
  • For pool, must have received all PacketAttrProducer and PacketAttrConsumer events.
  • This call could be skipped if block needs (or provides) only one element per packet.

Actions

  • Send number of packet elements to block.

Postconditions

  • If the count is zero, a PacketElementCount* event will be sent to the other endpoint(s) immediately.
  • If the count is zero, for the pool, packets may now be created.
Parameters
[in]blockThe block handle.
[in]countNumber of elements per packet.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamBlockSyncObjCount()

NvSciError NvSciStreamBlockSyncObjCount ( NvSciStreamBlock const  block,
uint32_t const  count 
)

Provides block's number of sync objects.

Used with producer and consumer to pass the number of sync objects they will write into to the other endpoint(s).

The sync object count is implicitly set to one.

If the block provides no sync object, the application must make this call, with count equal to zero, to advance the state of the stream and inform the other endpoint(s).

Preconditions

  • Block must have received SyncAttr event from the other endpoint(s).
  • This call could be skipped if the block provides only one sync object.

Actions

  • Send sync count to block. If count is zero, a SyncCount event will be sent to the other endpoint(s) immediately.

Postconditions

None.

Parameters
[in]blockBlock handle.
[in]countNumber of sync objects to be sent.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamBlockSyncObject()

NvSciError NvSciStreamBlockSyncObject ( NvSciStreamBlock const  block,
uint32_t const  index,
NvSciSyncObj const  syncObj 
)

Provides block's sync object.

Used with producer and consumer to pass the sync objects they will write into to the other endpoint(s).

Preconditions

  • Block must have received SyncAttr event from the other endpoint(s).
  • If the sync count is already set to zero by NvSciStreamBlockSyncObjCount, this call will fail.

Actions

  • Send sync object to block.
  • One sync object results in one SyncDesc event. When the last sync object is provided, these SyncDesc events and a SyncCount event will be sent to the other endpoint(s).

Postconditions

None.

Parameters
[in]blockBlock handle.
[in]indexIndex in list of sync objects
[in]syncObjHandle of sync object
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamBlockSyncRequirements()

NvSciError NvSciStreamBlockSyncRequirements ( NvSciStreamBlock const  block,
bool const  synchronousOnly,
NvSciSyncAttrList const  waitSyncAttrList 
)

Sets block sync object requirements.

Used with producer and consumer to establish their requirements for sync objects provided by the other endpoint(s).

Preconditions

  • Block must have received appropriate Connect event from the other endpoint(s).

Actions

  • A syncAttr event is sent to the other endpoint(s).

Postconditions

None.

Parameters
[in]blockBlock handle.
[in]synchronousOnlyIf true, endpoint cannot support sync objects
[in]waitSyncAttrListRequirements for endpoint to wait for sync objects
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamConsumerCreate()

NvSciError NvSciStreamConsumerCreate ( NvSciStreamBlock const  queue,
NvSciStreamBlock *const  consumer 
)

Creates a stream consumer block.

Create a block for the consumer end of a stream. All streams require at least one consumer block. Consumer blocks must have a queue attached to feed them pending frames. Consumer blocks have one input connection and no output connections.

Once the stream is fully connected, this block can be used to retrieve producer requirements and finalize consumer settings.

Preconditions: None.

Actions:

  • Creates a new instance of consumer block.
  • Binds the consumer block with the given queue block.

Postconditions:

  • The block is ready to be connected to other stream blocks.
  • The block can be monitored for events.
Parameters
[in]queueThe queue associated with the block.
[out]consumerHandle for new consumer block.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamConsumerPacketAcquire()

NvSciError NvSciStreamConsumerPacketAcquire ( NvSciStreamBlock const  consumer,
NvSciStreamCookie *const  cookie,
NvSciSyncFence *const  prefences 
)

Instructs the consumer to get a packet from the queue.

If a packet is available for reading, this function will retrieve it from the queue and assign it to the consumer.

The consumer may hold multiple packets for reading, and is not required to return them in the order they were obtained.

Preconditions

  • The PacketReady event for the next packet in the queue has been handled.
  • On safety-certified platforms, all packets have been accepted by the producer and the consumer.

Actions

  • Retrieves an available packet and returns it to the caller.

Postconditions

  • The packet now resides in the list owned by the consumer.
Parameters
[in]consumerConsumer block handle.
[out]cookieCookie identifying packet.
[out]prefencesArray of fences to wait for before using the packet. Must be at least large enough to hold one fence for each sync object created by the producer. If the sync object count is zero, may be NULL.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamConsumerPacketRelease()

NvSciError NvSciStreamConsumerPacketRelease ( NvSciStreamBlock const  consumer,
NvSciStreamPacket const  handle,
NvSciSyncFence const *const  postfences 
)

Returns a data packet to the stream.

Instructs the consumer to return a used data packet to the stream, where it will be sent to the producer for reuse.

Preconditions

  • The referenced packet is owned by the consumer.

Actions

  • The packet is sent back upstream. Once released by all consumers:
    • It will be put in the pool where it can be obtained by the producer.
    • A PacketReady event will be sent to the producer.

Postconditions

  • The packet will eventually reside in the list owned by the pool.
Parameters
[in]consumerConsumer block handle.
[in]handlePacket handle.
[in]postfencesA pointer to list of postfences for the data. The postfences in the array should be in the order according to the indices specified in NvSciStreamSyncDesc.

That is, if the sync object is set with index == 1, its fence should be the 2nd element in the postfences array.

Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamFifoQueueCreate()

NvSciError NvSciStreamFifoQueueCreate ( NvSciStreamBlock *const  queue)

Creates a FIFO queue block.

Create a block for tracking the list of packets available to be acquired. This is one available type of queue block. Every consumer must own a queue block, provided at the time the consumer is created.

A FIFO queue holds a list of packets, which will be acquired in the order they were presented.

If a new packet arrives, it is added to the end of the FIFO.

This type of queue is intended for consumer applications which must process every packet that is produced.

Once connected, the application does not directly interact with this block. The consumer block will communicate with it to obtain new packets.

Preconditions

None.

Actions

  • Initialize a queue to manage waiting packets.

Postconditions

  • The block is ready to be connected to other stream blocks.
Parameters
[out]queueHandle for the new queue block.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamIpcDstCreate()

NvSciError NvSciStreamIpcDstCreate ( NvSciIpcEndpoint const  ipcEndpoint,
NvSciSyncModule const  syncModule,
NvSciBufModule const  bufModule,
NvSciStreamBlock *const  ipc 
)

Creates an IPC destination block.

Creates the downstream half of an IPC block pair which allows packets to be transmitted between processes.

IPC destination blocks have one output connection and no input connection.

An IPC destination block connects to upstream through the ipcEndpoint used to create the block.

Preconditions

None.

Actions

  • Ready IPC endpoint.
  • Allocate buffers for data transmission.

Postconditions

  • The block is ready to be connected to other stream blocks.
Parameters
[in]ipcEndpointIPC endpoint handle.
[in]syncModuleNvSciSyncModule that is used to import a NvSciSyncAttrList across an IPC / IVC boundary.

This must be same module that was used to create NvSciSyncAttrList when specifying the associated NvSciStreamSyncAttr object.

Parameters
[in]bufModuleNvSciBufModule that is used to import a NvSciBufAttrList across an IPC / IVC boundary.

This must be same module that was used to create NvSciBufAttrList when specifying the associated NvSciStreamElementAttr object.

Parameters
[out]ipcHandle for new NvSciStream IPC destination block.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamIpcSrcCreate()

NvSciError NvSciStreamIpcSrcCreate ( NvSciIpcEndpoint const  ipcEndpoint,
NvSciSyncModule const  syncModule,
NvSciBufModule const  bufModule,
NvSciStreamBlock *const  ipc 
)

Creates an IPC source block.

Creates the upstream half of an IPC block pair which allows packets to be transmitted between processes.

IPC source blocks have one input connection and no output connection.

A IPC source block connects to downstream through the ipcEndpoint used to create the block.

Preconditions

None.

Actions

  • Ready IPC endpoint.
  • Allocate buffers for data transmission.

Postconditions

  • The block is ready to be connected to other stream blocks.
Parameters
[in]ipcEndpointIPC endpoint handle.
[in]syncModuleNvSciSyncModule that is used to import a NvSciSyncAttrList across an IPC / IVC boundary.

This must be same module that was used to create NvSciSyncAttrList when specifying the associated NvSciStreamSyncAttr object.

Parameters
[in]bufModuleNvSciBufModule that is used to import a NvSciBufAttrList across an IPC / IVC boundary.

This must be same module that was used to create NvSciBufAttrList when specifying the associated NvSciStreamElementAttr object.

Parameters
[out]ipcHandle for the new NvSciStream IPC source block.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamMailboxQueueCreate()

NvSciError NvSciStreamMailboxQueueCreate ( NvSciStreamBlock *const  queue)

Creates a mailbox queue block.

Create a block for tracking the next packet available to be acquired. This is one available type of queue block. Every consumer must own a queue block, provided at the time the consumer is created.

A mailbox queue holds a single packet. If a new packet arrives, the old one is replaced and returned to the pool for reuse without ever being acquired.

This type of queue is intended for consumer applications which don't need to process every packet and always wish to have the latest input available.

Once connected, the application does not directly interact with this block. The consumer block will communicate with it to obtain new packets.

Preconditions

None.

Actions

  • Initialize a queue to hold a single packet for acquire.

Postconditions

  • The block is ready to be connected to other stream blocks.
Parameters
[out]queueHandle for new queue block.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamMulticastCreate()

NvSciError NvSciStreamMulticastCreate ( uint32_t const  outputCount,
NvSciStreamBlock *const  multicast 
)

Creates a multicast block.

Create a block allowing for one input and one or more outputs.

Multicast block broadcasts messages sent from upstream to all of the downstream blocks.

Mulitcast block aggregates messages of the same type from downstreams into one before sending it upstream.

Preconditions

None.

Actions

  • Initialize a block that takes one input and one or more outputs.

Postconditions

  • The block is ready to be connected to other stream blocks.
Parameters
[in]outputCountnumber of output blocks that will be connected.
[out]multicastHandle for the new multicast block.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamPoolPacketCreate()

NvSciError NvSciStreamPoolPacketCreate ( NvSciStreamBlock const  pool,
NvSciStreamCookie const  cookie,
NvSciStreamPacket *const  handle 
)

Adds a new packet to the pool.

Creates a new packet for the pool to make available to the producer. The description should contain the pool's cookie for the new packet.

Preconditions

  • Final packet attributes must have been specified for the pool.
  • For static pool, the number of packets already created has not reached the limit.

Actions

  • A new packet handle is assigned to the packet and returned to the caller.
  • If the element count is set to zero, a PacketCreate event will be sent to the producer and the consumer.

Postconditions

  • The application can register buffers to the created packet.
Parameters
[in]poolPool block handle.
[in]cookiePool's cookie for the packet.
[out]handleNew handle assigned to the packet.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamPoolPacketDelete()

NvSciError NvSciStreamPoolPacketDelete ( NvSciStreamBlock const  pool,
NvSciStreamPacket const  handle 
)

Removes a packet from the pool.

Schedules an existing packet to be removed from the pool. If the packet is currently in the pool, it is removed right away. Otherwise this is deferred until the packet returns to the pool.

Note: This will not be supported in the safety-certified driver. It is only to support non-safety cases where buffers can be added and removed at any time.

Preconditions

  • Specified packet must exist.

Actions

  • When the specified packet is returned to the pool, the pool releases resources associated with it and sends a PacketDelete event to the producer and consumer.

Postconditions

  • The packet may no longer be used for pool operations.
Parameters
[in]poolPool block handle.
[in]handlePacket handle.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamPoolPacketInsertBuffer()

NvSciError NvSciStreamPoolPacketInsertBuffer ( NvSciStreamBlock const  pool,
NvSciStreamPacket const  handle,
uint32_t const  index,
NvSciBufObj const  bufObj 
)

Registers a buffer to the packet.

Preconditions

  • The number of buffers already registered to the packet hasn't reached the number set by NvSciStreamBlockPacketElementCount.

Actions

  • The buffer is added to the packet.

Postconditions

  • When the last buffer is added to the packet, a PacketCreate and PacketElement event (one per packet element) will be sent to producer and consumer.
Parameters
[in]poolPool block handle.
[in]handlePacket handle.
[in]indexIndex of element within packet.
[in]bufObjHandle of buffer for element.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamProducerCreate()

NvSciError NvSciStreamProducerCreate ( NvSciStreamBlock const  pool,
NvSciStreamBlock *const  producer 
)

Creates a stream producer block.

Create a block for the producer end of a stream. All streams require one producer block. Producer blocks must have a pool attached to feed them their buffers. Producer blocks have one output connection and no input connections.

Once the stream is fully connected, this block can be used to retrieve consumer requirements and finalize producer settings.

Preconditions: None.

Actions:

  • Creates a new instance of producer block.
  • Binds the producer block with the given pool block.

Postconditions:

  • The block is ready to be connected to other stream blocks.
  • The block can be monitored for events.
Parameters
[in]poolThe pool associated with the block.
[out]producerHandle for new producer block.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamProducerPacketGet()

NvSciError NvSciStreamProducerPacketGet ( NvSciStreamBlock const  producer,
NvSciStreamCookie *const  cookie,
NvSciSyncFence *const  prefences 
)

Instructs the producer to get a packet from the pool.

If a packet is available for writing, this function will retrieve it from the pool and assign it to the producer.

The producer may hold multiple packets for rendering, and is not required to present them in the order they were obtained.

Preconditions

  • The PacketReady event for the next packet in the pool has been handled.
  • On safety-certified platforms, all packets have been accepted by the producer and the consumer.

Actions

  • Retrieves an available packet and returns it to the caller.

Postconditions

  • The packet now resides in the list owned by the producer.
Parameters
[in]producerProducer block handle.
[out]cookieCookie identifying packet.
[out]prefencesArray of fences to wait for before using the packet. Must be at least large enough to hold one fence for each sync object created by the consumer. If the sync object count is zero, may be NULL.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamProducerPacketPresent()

NvSciError NvSciStreamProducerPacketPresent ( NvSciStreamBlock const  producer,
NvSciStreamPacket const  handle,
NvSciSyncFence const *const  postfences 
)

Inserts a data packet into the stream.

Instructs the producer to insert a completed data packet into the stream, where it will be sent to the consumer(s) for acquisition.

Preconditions

  • The referenced packet is owned by the producer.

Actions

  • The packet is sent to the queue(s) where it will be held until acquired by the consumer or returned without acquisition.
  • If one is not already pending, a PacketReady event will be sent to each consumer.

Postconditions

  • The packet now resides in the list owned by the queue(s).
Parameters
[in]producerProducer block handle.
[in]handlePacket handle.
[in]postfencesA pointer to array of postfences for the data. The postfences in the array should be in the order according to the indices specified in NvSciStreamSyncDesc. That is, if the sync object is set with index == 1, its fence should be the 2nd element in the postfences array.
Returns
NvSciError, the completion code of this operation.

◆ NvSciStreamStaticPoolCreate()

NvSciError NvSciStreamStaticPoolCreate ( uint32_t const  numPackets,
NvSciStreamBlock *const  pool 
)

Creates a static stream pool block.

Create a block for management of a stream's packet pool. Every producer must own a pool block, provided at the producer's creation.

A static pool has a fixed number of packets which must be fully defined before streaming begins, and is intended for safety-certified usage.

Once the stream is fully connected and the application (which may or may not be the same as the producer application) has determined the packet requirements, this block can be used to bind memory buffers to each packet.

Preconditions

None.

Actions

  • Allocate data structures to describe packets.
  • Initialize queue of available packets.

Postconditions

  • The block is ready to be connected to other stream blocks.
  • The block can be monitored for events.
Parameters
[in]numPacketsNumber of packets.
[out]poolHandle for the new pool block.
Returns
NvSciError, the completion code of this operation.