ncGraphQueueInferenceWithFifoElem()

Info	Value
Header	mvnc.h
Library	libmvnc.so
Version	2.0
See also	struct ncGraphHandle_t, struct ncFifoHandle_t, ncGraphQueueInference(), ncFifoWriteElem()

Overview

This function writes an element to a FIFO, usually an input tensor for inference, and queues an inference to be processed by a graph. This is a convenient way to write an input tensor and queue an inference in one call.

Prototype

ncStatus_t ncGraphQueueInferenceWithFifoElem(
    struct ncGraphHandle_t* graphHandle,
    struct ncFifoHandle_t* fifoIn,
    struct ncFifoHandle_t* fifoOut, 
    const void* inputTensor,
    unsigned int* inputTensorLength, 
    void* userParam
);

Parameters

Name	Type	Description
graphHandle	struct ncGraphHandle_t*	A pointer to an ncGraphHandle_t struct for the graph that will be used for inference. The graph state must be NC_GRAPH_ALLOCATED.
fifoIn	struct ncFifoHandle_t*	A pointer to the ncFifoHandle_t struct for the input queue from which the tensor will be read. The FIFO state must be NC_FIFO_ALLOCATED.
fifoOut	struct ncFifoHandle_t*	A pointer to the ncFifoHandle_t struct for the output queue on which the inference result will be placed. The FIFO state must be NC_FIFO_ALLOCATED.
inputTensor	const void*	A pointer to a tensor data buffer that contains data in the format specified by the FIFO’s NC_RW_FIFO_DATA_TYPE option. This data is typically a representation of each color channel in each pixel of an image.
inputTensorLength	unsigned int*	A pointer to an unsigned int that contains the length, in bytes, of the buffer that the inputTensor parameter points to. If the size of the input tensor does not match the expected input size for this FIFO, the return status code will be NC_INVALID_DATA_LENGTH and inputTensorLength will be set to the expected input size.
userParam	void*	A pointer to additional user data to associate with the input tensor, or NULL. The pointer value (not the data that it points to) will be copied, stored, and then returned with the inference result with ncFifoReadElem(). This pointer can point to anything that the caller would like to associate with the inference result, such as the original inference input or a window handle. The caller is responsible for allocating and freeing any memory that this pointer references.

Return

An appropriate value from the ncStatus_t enumeration.

If the size of the input tensor does not match the expected input size for this FIFO, the return status code will be NC_INVALID_DATA_LENGTH and the inputTensorLength will be set to the expected input size.

Notes

This function takes the place of explicit calls to ncFifoWriteElem() and ncGraphQueueInference().
The input FIFO must allow write access for the API and the output FIFO must allow read access for the API.
ncFifoWriteElem(), which is called internally by this function, is a blocking call if NC_RW_FIFO_DONT_BLOCK is false. If the input FIFO is full this function will not return until there is space to write to the FIFO.
- The input FIFO’s capacity is set when the FIFO is allocated with ncGraphAllocateWithFifos()/ncGraphAllocateWithFifosEx() or ncFifoAllocate().
- You can check the capacity and the current fill level of the input FIFO with ncFifoGetOption() for NC_RO_FIFO_CAPACITY and NC_RO_FIFO_WRITE_FILL_LEVEL.

Example

#include <stdio.h>
#include <stdlib.h>
#include <mvnc.h>

int main() {
    // You can check that this return code is equal to NC_OK after each API function call
    // This is omitted in this example for better readability
    ncStatus_t retCode;

    // Initialize and open a device
    struct ncDeviceHandle_t* deviceHandle;
    retCode = ncDeviceCreate(0, &deviceHandle);
    retCode = ncDeviceOpen(deviceHandle);

    // Load a graph from file
    // void* graphBuffer = ...
    // unsigned int graphBufferLength = ...
    
    // Initialize the graph
    struct ncGraphHandle_t* graphHandle;
    retCode = ncGraphCreate("graph1", &graphHandle);
       
    // CONVENIENCE FUNCTION: Allocate the graph to the device and create input/output FIFOs with default options
    // Alternatively, use ncGraphAllocateWithFifosEx() to do this with explicit FIFO options
    struct ncFifoHandle_t* inputFIFO;
    struct ncFifoHandle_t* outputFIFO;
    retCode = ncGraphAllocateWithFifos(deviceHandle, graphHandle, graphBuffer, graphBufferLength, &inputFIFO, &outputFIFO);
    free(graphBuffer);

    // Read and preprocess input...
    // float* imageBuffer = ...
    // unsigned int imageBufferLength = ...

    // Write the image to the input FIFO and queue the inference
    retCode = ncGraphQueueInferenceWithFifoElem(
                    graphHandle, &inputFIFO, &outputFIFO,
                    imageBuffer, &imageBufferLength, 0);    
    
    // Get the results from the output FIFO
    void* result;
    unsigned int fifoOutputSize = 0;
    unsigned int optionDataLen = sizeof(fifoOutputSize);
    ncFifoGetOption(outFifoHandlePtr, NC_RO_FIFO_ELEMENT_DATA_SIZE, &fifoOutputSize, &optionDataLen);
    result = malloc(fifoOutputSize);    
    retCode = ncFifoReadElem(outputFIFO, result, &fifoOutputSize, NULL);
    free(result);

    // Do something with the results...

    // Clean up
    retCode = ncFifoDestroy(&inputFIFO);
    retCode = ncFifoDestroy(&outputFIFO);
    retCode = ncGraphDestroy(&graphHandle);
    retCode = ncDeviceClose(deviceHandle);
    retCode = ncDeviceDestroy(&deviceHandle);
}