sources/libs/nvdewarper/Warp360/include/NVWarp360.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2017-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
 
#ifndef __NVWARP360_H__
#define __NVWARP360_H__
 
#include <cuda_runtime.h>
#include <stdint.h>
 
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if defined(_WIN32) || defined(_WIN64)
    #define NVWARPAPI __stdcall 
#else /* !_WINxx */
    #define NVWARPAPI           
#endif /* _WINxx */
 
 
typedef enum nvwarpResult
{
    NVWARP_SUCCESS                  = 0,            
    NVWARP_ERR_GENERAL              = 1,            
    NVWARP_ERR_UNIMPLEMENTED        = 2,            
    NVWARP_ERR_DOMAIN               = 3,            
    NVWARP_ERR_MISSING_PARAMETERS   = 4,            
    NVWARP_ERR_PARAMETER            = 5,            
    NVWARP_ERR_INITIALIZATION       = 6,            
    NVWARP_ERR_CUDA_MEMORY          = 7,            
    NVWARP_ERR_CUDA_LAUNCH          = 8,            
    NVWARP_ERR_CUDA_DRIVER          = 9,            
    NVWARP_ERR_CUDA_NO_KERNEL       = 10,           
    NVWARP_ERR_CUDA                 = 11,           
    NVWARP_ERR_APPROXIMATE          = 12,           
    NVWARP_ERR_MAX                  = 0x7fffffff    
} nvWarpResult; 
 
// These are not used directly by the API.
typedef enum nvwarpSurface_t
{
    NVSURF_PERSPECTIVE      = 0,                        
    NVSURF_FISHEYE          = 1,                        
    NVSURF_EQUIRECT         = 2,                        
    NVSURF_CYLINDER         = 3,                        
    NVSURF_ROTCYLINDER      = 4,                        
    NVSURF_PUSHBROOM        = 5,                        
    NVSURF_PANINI           = 6,                        
    NVSURF_STEREOGRAPHIC    = 7,                        
 
    NVSURF_BITS             = 8,                        
    NVSURF_UNKNOWN          = ((1 << NVSURF_BITS) - 1), 
    NVSURF_MASK             = ((1 << NVSURF_BITS) - 1), 
    NVSURF_MAX              = 0x7fffffff                
} nvwarpSurface_t;
 
typedef enum nvwarpType_t
{
    NVWARP_EQUIRECT_CYLINDER        = (NVSURF_EQUIRECT    << NVSURF_BITS) | NVSURF_CYLINDER,        
    NVWARP_EQUIRECT_EQUIRECT        = (NVSURF_EQUIRECT    << NVSURF_BITS) | NVSURF_EQUIRECT,        
    NVWARP_EQUIRECT_FISHEYE         = (NVSURF_EQUIRECT    << NVSURF_BITS) | NVSURF_FISHEYE,         
    NVWARP_EQUIRECT_PANINI          = (NVSURF_EQUIRECT    << NVSURF_BITS) | NVSURF_PANINI,          
    NVWARP_EQUIRECT_PERSPECTIVE     = (NVSURF_EQUIRECT    << NVSURF_BITS) | NVSURF_PERSPECTIVE,     
    NVWARP_EQUIRECT_PUSHBROOM       = (NVSURF_EQUIRECT    << NVSURF_BITS) | NVSURF_PUSHBROOM,       
    NVWARP_EQUIRECT_STEREOGRAPHIC   = (NVSURF_EQUIRECT    << NVSURF_BITS) | NVSURF_STEREOGRAPHIC,   
    NVWARP_EQUIRECT_ROTCYLINDER     = (NVSURF_EQUIRECT    << NVSURF_BITS) | NVSURF_ROTCYLINDER,     
    NVWARP_FISHEYE_CYLINDER         = (NVSURF_FISHEYE     << NVSURF_BITS) | NVSURF_CYLINDER,        
    NVWARP_FISHEYE_EQUIRECT         = (NVSURF_FISHEYE     << NVSURF_BITS) | NVSURF_EQUIRECT,        
    NVWARP_FISHEYE_FISHEYE          = (NVSURF_FISHEYE     << NVSURF_BITS) | NVSURF_FISHEYE,         
    NVWARP_FISHEYE_PANINI           = (NVSURF_FISHEYE     << NVSURF_BITS) | NVSURF_PANINI,          
    NVWARP_FISHEYE_PERSPECTIVE      = (NVSURF_FISHEYE     << NVSURF_BITS) | NVSURF_PERSPECTIVE,     
    NVWARP_FISHEYE_PUSHBROOM        = (NVSURF_FISHEYE     << NVSURF_BITS) | NVSURF_PUSHBROOM,       
    NVWARP_FISHEYE_ROTCYLINDER      = (NVSURF_FISHEYE     << NVSURF_BITS) | NVSURF_ROTCYLINDER,     
    NVWARP_PERSPECTIVE_EQUIRECT     = (NVSURF_PERSPECTIVE << NVSURF_BITS) | NVSURF_EQUIRECT,        
    NVWARP_PERSPECTIVE_PANINI       = (NVSURF_PERSPECTIVE << NVSURF_BITS) | NVSURF_PANINI,          
    NVWARP_PERSPECTIVE_PERSPECTIVE  = (NVSURF_PERSPECTIVE << NVSURF_BITS) | NVSURF_PERSPECTIVE,     
    NVWARP_NONE                     = 0xffffffff                                                    
} nvwarpType_t; 
 
 
 
 
 
 
struct nvwarpParams_t;
typedef struct nvwarpParams_t nvwarpParams_t;
 
 
void NVWARPAPI nvwarpInitParams(nvwarpParams_t *params);
 
 
typedef struct nvwarpParams_t
{
    // Warp type selector
    nvwarpType_t    type;                       
 
    // Source specification
    uint32_t        srcWidth;                   
    uint32_t        srcHeight;                  
    float           srcX0;                      
    float           srcY0;                      
    float           srcFocalLen;                
    float           srcRadius;                  
 
    float           dist[5];                    
 
    // Destination specification
    uint32_t        dstWidth;                   
    uint32_t        dstHeight;                  
 
    // View specification
    float           rotAngles[3];               
    char            rotAxes[4];                 
 
    float           topAngle;                   
    float           bottomAngle;                
 
    void*           userData;                   
 
    // Warp controls
    float           control[4];                 
 
#ifdef __cplusplus
    nvwarpParams_t() { nvwarpInitParams(this); }
#endif // __cplusplus
 
} nvwarpParams_t;   
 
 
nvwarpResult NVWARPAPI nvwarpComputeParamsSrcFocalLength(nvwarpParams_t *params, float angle, float radius);
 
nvwarpResult NVWARPAPI nvwarpComputeParamsOutputResolution(nvwarpParams_t *params, float aspectRatio);
 
nvwarpResult NVWARPAPI nvwarpComputeParamsAxialAngleRange(const nvwarpParams_t *params, float minMaxXY[4]);
 
nvwarpResult NVWARPAPI nvwarpComputeBoxAxialAngleRange(const nvwarpParams_t *params, const float srcBoundingBox[4], float minMaxXY[4]);
 
 
 
 
 
struct nvwarpObject;
 
typedef struct nvwarpObject *nvwarpHandle;
 
nvwarpResult NVWARPAPI nvwarpCreateInstance(nvwarpHandle *han);
 
void         NVWARPAPI nvwarpDestroyInstance(nvwarpHandle han);
 
 
uint32_t NVWARPAPI nvwarpVersion();
 
#define NVWARP_VERSION_MAJOR(version)       (((v) >> 24) & 0xff)
 
#define NVWARP_VERSION_MINOR(version)       (((v) >> 16) & 0xff)
 
#define NVWARP_VERSION_REVISION(version)    (((v) >>  8) & 0xff)
 
const char* NVWARPAPI nvwarpErrorStringFromCode(nvwarpResult err);
 
 
 
 
    // Set the Warp Object from the Parameter Block //
 
nvwarpResult NVWARPAPI nvwarpSetParams(nvwarpHandle han, const nvwarpParams_t *params);
 
void         NVWARPAPI nvwarpGetParams(const nvwarpHandle han, nvwarpParams_t *params);
 
 
    // Warp Type //
 
nvwarpResult NVWARPAPI nvwarpSetWarpType(nvwarpHandle han, nvwarpType_t type);
 
nvwarpType_t NVWARPAPI nvwarpGetWarpType(const nvwarpHandle han);
 
 
    // CUDA Block Size //
 
void NVWARPAPI nvwarpSetBlock(nvwarpHandle han, dim3 dim_block);
 
void NVWARPAPI nvwarpGetBlock(const nvwarpHandle han, dim3 *dim_block);
 
 
    // Pixel Phase //
 
void NVWARPAPI nvwarpSetPixelPhase(nvwarpHandle han, uint32_t phase);
 
uint32_t NVWARPAPI nvwarpGetPixelPhase(const nvwarpHandle han);
 
 
    // Source Dimensions //
 
void NVWARPAPI nvwarpSetSrcWidthHeight(nvwarpHandle han, uint32_t w, uint32_t h);
 
void NVWARPAPI nvwarpGetSrcWidthHeight(const nvwarpHandle han, uint32_t wh[2]);
 
 
    // Source focal length //
 
void NVWARPAPI nvwarpSetSrcFocalLengths(nvwarpHandle han, float fl, float fy);
 
nvwarpResult NVWARPAPI nvwarpComputeSrcFocalLength(nvwarpHandle han, nvwarpType_t warpType, float radius, float angle, float dist[5]);
 
float NVWARPAPI nvwarpGetSrcFocalLength(const nvwarpHandle han, float *fy);
 
 
    // Source Principal Point //
 
void NVWARPAPI nvwarpSetSrcPrincipalPoint(nvwarpHandle han, const float xy[2], uint32_t relToCenter);
 
void NVWARPAPI nvwarpGetSrcPrincipalPoint(const nvwarpHandle han, float xy[2], uint32_t relToCenter);
 
 
    // Source Fisheye Radius //
 
void NVWARPAPI nvwarpSetSrcRadius(nvwarpHandle han, float r);
 
float NVWARPAPI nvwarpGetSrcRadius(const nvwarpHandle han);
 
 
    // Distortion //
 
void NVWARPAPI nvwarpSetDistortion(nvwarpHandle han, const float d[5]);
 
void NVWARPAPI nvwarpGetDistortion(const nvwarpHandle han, float d[5]);
 
 
    // Rotation //
 
void NVWARPAPI nvwarpSetRotation(nvwarpHandle han, const float R[9]);
 
void NVWARPAPI nvwarpSetEulerRotation(nvwarpHandle han, const float *angles, const char *axes);
 
void NVWARPAPI nvwarpGetRotation(const nvwarpHandle han, float R[9]);
 
 
    // Destination dimensions //
 
void NVWARPAPI nvwarpSetDstWidthHeight(nvwarpHandle han, uint32_t w, uint32_t h);
 
void NVWARPAPI nvwarpGetDstWidthHeight(const nvwarpHandle han, uint32_t wh[2]);
 
 
    // Destination focal length //
 
void NVWARPAPI nvwarpSetDstFocalLengths(nvwarpHandle han, float fl, float fy);
 
void NVWARPAPI nvwarpComputeDstFocalLength(nvwarpHandle han, float topAngle, float bottomAngle, uint32_t dstWidth, uint32_t dstHeight);
 
 
nvwarpResult NVWARPAPI nvwarpComputeDstFocalLengths(nvwarpHandle han, float topAxialAngle, float botAxialAngle, float leftAxialAngle, float rightAxialAngle,
    uint32_t dstWidth, uint32_t dstHeight);
 
float NVWARPAPI nvwarpGetDstFocalLength(const nvwarpHandle han, float *fy);
 
 
    // Destination Principal Point //
 
void NVWARPAPI nvwarpSetDstPrincipalPoint(nvwarpHandle han, const float xy[2], uint32_t relToCenter);
 
void NVWARPAPI nvwarpGetDstPrincipalPoint(const nvwarpHandle han, float xy[2], uint32_t relToCenter);
 
 
    // Control Parameters //
 
void NVWARPAPI nvwarpSetControl(nvwarpHandle han, uint32_t index, float control);
 
float NVWARPAPI nvwarpGetControl(const nvwarpHandle han, uint32_t index);
 
 
    // User Data Pointer //
 
void NVWARPAPI nvwarpSetUserData(nvwarpHandle han, void *userData);
 
void* NVWARPAPI nvwarpGetUserData(nvwarpHandle han);
 
 
 
 
 
    // Warp Images //
 
nvwarpResult NVWARPAPI nvwarpWarpSurface(const nvwarpHandle han, cudaStream_t stream, cudaTextureObject_t srcTex, cudaSurfaceObject_t dstSurface);
 
nvwarpResult NVWARPAPI nvwarpWarpBuffer(const nvwarpHandle han, cudaStream_t stream, cudaTextureObject_t srcTex, void *dstAddr, size_t dstRowBytes);
 
 
    // Warp Coordinates Between Source and Destination //
 
nvwarpResult NVWARPAPI nvwarpWarpCoordinates(const nvwarpHandle han, uint32_t numPts, const float *inPtsXY, float *outPtsXY);
 
nvwarpResult NVWARPAPI nvwarpInverseWarpCoordinates(const nvwarpHandle han, uint32_t numPts, const float *inPtsXY, float *outPtsXY);
 
 
    // Ray <--> Coordinate Conversion //
 
nvwarpResult NVWARPAPI nvwarpSrcToRay(const nvwarpHandle han, uint32_t numPts, const float *pts2D, float *rays3D);
 
nvwarpResult NVWARPAPI nvwarpDstToRay(const nvwarpHandle han, uint32_t numPts, const float *pts2D, float *rays3D);
 
nvwarpResult NVWARPAPI nvwarpSrcFromRay(const nvwarpHandle han, uint32_t numRays, const float *rays3D, float *pts2D);
 
nvwarpResult NVWARPAPI nvwarpDstFromRay(const nvwarpHandle han, uint32_t numRays, const float *rays3D, float *pts2D);
 
 
    // Angle <--> Coordinate Conversion //
 
nvwarpResult NVWARPAPI nvwarpComputeSrcAngularFromPixelCoordinates(const nvwarpHandle han, uint32_t numPts, const float *pts2D, float *ang2D);
 
nvwarpResult NVWARPAPI nvwarpComputeSrcPixelFromAngularCoordinates(const nvwarpHandle han, uint32_t numPts, const float *ang2D, float *pts2D);
 
nvwarpResult NVWARPAPI nvwarpComputeDstAngularFromPixelCoordinates(const nvwarpHandle han, uint32_t numPts, const float *pts2D, float *ang2D);
 
nvwarpResult NVWARPAPI nvwarpComputeDstPixelFromAngularCoordinates(const nvwarpHandle han, uint32_t numPts, const float *ang2D, float *pts2D);
 
 
    // Miscellaneous //
 
void NVWARPAPI nvwarpConvertTransformBetweenYUpandYDown(const float fr[9], float to[9]);
 
 
 
 
 
 
typedef struct nvwarpYUVRGBParams_t
{
    uint32_t width;     
    uint32_t height;    
    uint32_t cLocation; 
    float   ry,         
            rcb,        
            rcr,        
            gy,         
            gcb,        
            gcr,        
            by,         
            bcb,        
            bcr;        
    float   yOffset,    
            cOffset;    
} nvwarpYUVRGBParams_t;
 
 
void NVWARPAPI nvwarpComputeYCbCr2RgbMatrix(nvwarpYUVRGBParams_t *p, uint32_t matrix_coefficients, uint32_t video_full_range_flag, uint32_t bit_depth, uint32_t normalized_input, uint32_t normalized_output);
 
 
nvwarpResult NVWARPAPI nvwarpConvertYUVNV12ToRGBA(cudaStream_t stream, const nvwarpYUVRGBParams_t *params, const void *yuv, size_t yuvRowBytes, void *dst, size_t dstRowBytes);
 
 
 
 
 
 
nvwarpResult NVWARPAPI nvwarpMultiWarp360(cudaStream_t stream,
    const nvwarpYUVRGBParams_t *yuvParams, const void *yuvBuffer, size_t yuvRowBytes,
    void *rgbBuffer, size_t rgbRowBytes, cudaTextureObject_t rgbTex,
    uint32_t numWarps, const nvwarpParams_t *paramArray, void **dstBuffers, const size_t *dstRowBytes);
 
 
#ifdef __cplusplus
}
#endif // __cplusplus
 
 
#endif /* __NVWARP360_H__ */