1// ======================================================================== //
2// Copyright 2009-2019 Intel Corporation //
3// //
4// Licensed under the Apache License, Version 2.0 (the "License"); //
5// you may not use this file except in compliance with the License. //
6// You may obtain a copy of the License at //
7// //
8// http://www.apache.org/licenses/LICENSE-2.0 //
9// //
10// Unless required by applicable law or agreed to in writing, software //
11// distributed under the License is distributed on an "AS IS" BASIS, //
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. //
13// See the License for the specific language governing permissions and //
14// limitations under the License. //
15// ======================================================================== //
16
17#pragma once
18
19#include <stddef.h>
20#include <stdbool.h>
21#include <stdint.h>
22
23#include "version.h"
24
25#if defined(__cplusplus)
26extern "C" {
27#endif
28
29#ifndef OIDN_API
30#if defined(_WIN32) && !defined(OIDN_STATIC_LIB)
31# define OIDN_API __declspec(dllimport)
32#else
33# define OIDN_API
34#endif
35#endif
36
37// ----------------------------------------------------------------------------
38// Device
39// ----------------------------------------------------------------------------
40
41// Device types
42typedef enum
43{
44 OIDN_DEVICE_TYPE_DEFAULT = 0, // select device automatically
45
46 OIDN_DEVICE_TYPE_CPU = 1, // CPU device
47} OIDNDeviceType;
48
49// Error codes
50typedef enum
51{
52 OIDN_ERROR_NONE = 0, // no error occurred
53 OIDN_ERROR_UNKNOWN = 1, // an unknown error occurred
54 OIDN_ERROR_INVALID_ARGUMENT = 2, // an invalid argument was specified
55 OIDN_ERROR_INVALID_OPERATION = 3, // the operation is not allowed
56 OIDN_ERROR_OUT_OF_MEMORY = 4, // not enough memory to execute the operation
57 OIDN_ERROR_UNSUPPORTED_HARDWARE = 5, // the hardware (e.g. CPU) is not supported
58 OIDN_ERROR_CANCELLED = 6, // the operation was cancelled by the user
59} OIDNError;
60
61// Error callback function
62typedef void (*OIDNErrorFunction)(void* userPtr, OIDNError code, const char* message);
63
64// Device handle
65typedef struct OIDNDeviceImpl* OIDNDevice;
66
67// Creates a new device.
68OIDN_API OIDNDevice oidnNewDevice(OIDNDeviceType type);
69
70// Retains the device (increments the reference count).
71OIDN_API void oidnRetainDevice(OIDNDevice device);
72
73// Releases the device (decrements the reference count).
74OIDN_API void oidnReleaseDevice(OIDNDevice device);
75
76// Sets a boolean parameter of the device.
77OIDN_API void oidnSetDevice1b(OIDNDevice device, const char* name, bool value);
78
79// Sets an integer parameter of the device.
80OIDN_API void oidnSetDevice1i(OIDNDevice device, const char* name, int value);
81
82// Gets a boolean parameter of the device.
83OIDN_API bool oidnGetDevice1b(OIDNDevice device, const char* name);
84
85// Gets an integer parameter of the device (e.g. "version").
86OIDN_API int oidnGetDevice1i(OIDNDevice device, const char* name);
87
88// Sets the error callback function of the device.
89OIDN_API void oidnSetDeviceErrorFunction(OIDNDevice device, OIDNErrorFunction func, void* userPtr);
90
91// Returns the first unqueried error code stored in the device for the current
92// thread, optionally also returning a string message (if not NULL), and clears
93// the stored error. Can be called with a NULL device as well to check why a
94// device creation failed.
95OIDN_API OIDNError oidnGetDeviceError(OIDNDevice device, const char** outMessage);
96
97// Commits all previous changes to the device.
98// Must be called before first using the device (e.g. creating filters).
99OIDN_API void oidnCommitDevice(OIDNDevice device);
100
101// ----------------------------------------------------------------------------
102// Buffer
103// ----------------------------------------------------------------------------
104
105// Formats for images and other data stored in buffers
106typedef enum
107{
108 OIDN_FORMAT_UNDEFINED = 0,
109
110 // 32-bit single-precision floating point scalar and vector formats
111 OIDN_FORMAT_FLOAT = 1,
112 OIDN_FORMAT_FLOAT2 = 2,
113 OIDN_FORMAT_FLOAT3 = 3,
114 OIDN_FORMAT_FLOAT4 = 4,
115} OIDNFormat;
116
117// Access modes for mapping buffers
118typedef enum
119{
120 OIDN_ACCESS_READ = 0, // read-only access
121 OIDN_ACCESS_WRITE = 1, // write-only access
122 OIDN_ACCESS_READ_WRITE = 2, // read and write access
123 OIDN_ACCESS_WRITE_DISCARD = 3, // write-only access, previous contents discarded
124} OIDNAccess;
125
126// Buffer handle
127typedef struct OIDNBufferImpl* OIDNBuffer;
128
129// Creates a new buffer (data allocated and owned by the device).
130OIDN_API OIDNBuffer oidnNewBuffer(OIDNDevice device, size_t byteSize);
131
132// Creates a new shared buffer (data allocated and owned by the user).
133OIDN_API OIDNBuffer oidnNewSharedBuffer(OIDNDevice device, void* ptr, size_t byteSize);
134
135// Maps a region of the buffer to host memory.
136// If byteSize is 0, the maximum available amount of memory will be mapped.
137OIDN_API void* oidnMapBuffer(OIDNBuffer buffer, OIDNAccess access, size_t byteOffset, size_t byteSize);
138
139// Unmaps a region of the buffer.
140// mappedPtr must be a pointer returned by a previous call to oidnMapBuffer.
141OIDN_API void oidnUnmapBuffer(OIDNBuffer buffer, void* mappedPtr);
142
143// Retains the buffer (increments the reference count).
144OIDN_API void oidnRetainBuffer(OIDNBuffer buffer);
145
146// Releases the buffer (decrements the reference count).
147OIDN_API void oidnReleaseBuffer(OIDNBuffer buffer);
148
149// ----------------------------------------------------------------------------
150// Filter
151// ----------------------------------------------------------------------------
152
153// Progress monitor callback function
154typedef bool (*OIDNProgressMonitorFunction)(void* userPtr, double n);
155
156// Filter handle
157typedef struct OIDNFilterImpl* OIDNFilter;
158
159// Creates a new filter of the specified type (e.g. "RT").
160OIDN_API OIDNFilter oidnNewFilter(OIDNDevice device, const char* type);
161
162// Retains the filter (increments the reference count).
163OIDN_API void oidnRetainFilter(OIDNFilter filter);
164
165// Releases the filter (decrements the reference count).
166OIDN_API void oidnReleaseFilter(OIDNFilter filter);
167
168// Sets an image parameter of the filter (stored in a buffer).
169// If bytePixelStride and/or byteRowStride are zero, these will be computed automatically.
170OIDN_API void oidnSetFilterImage(OIDNFilter filter, const char* name,
171 OIDNBuffer buffer, OIDNFormat format,
172 size_t width, size_t height,
173 size_t byteOffset,
174 size_t bytePixelStride, size_t byteRowStride);
175
176// Sets an image parameter of the filter (owned by the user).
177// If bytePixelStride and/or byteRowStride are zero, these will be computed automatically.
178OIDN_API void oidnSetSharedFilterImage(OIDNFilter filter, const char* name,
179 void* ptr, OIDNFormat format,
180 size_t width, size_t height,
181 size_t byteOffset,
182 size_t bytePixelStride, size_t byteRowStride);
183
184// Sets a boolean parameter of the filter.
185OIDN_API void oidnSetFilter1b(OIDNFilter filter, const char* name, bool value);
186
187// Gets a boolean parameter of the filter.
188OIDN_API bool oidnGetFilter1b(OIDNFilter filter, const char* name);
189
190// Sets an integer parameter of the filter.
191OIDN_API void oidnSetFilter1i(OIDNFilter filter, const char* name, int value);
192
193// Gets an integer parameter of the filter.
194OIDN_API int oidnGetFilter1i(OIDNFilter filter, const char* name);
195
196// Sets a float parameter of the filter.
197OIDN_API void oidnSetFilter1f(OIDNFilter filter, const char* name, float value);
198
199// Gets a float parameter of the filter.
200OIDN_API float oidnGetFilter1f(OIDNFilter filter, const char* name);
201
202// Sets the progress monitor callback function of the filter.
203OIDN_API void oidnSetFilterProgressMonitorFunction(OIDNFilter filter, OIDNProgressMonitorFunction func, void* userPtr);
204
205// Commits all previous changes to the filter.
206// Must be called before first executing the filter.
207OIDN_API void oidnCommitFilter(OIDNFilter filter);
208
209// Executes the filter.
210OIDN_API void oidnExecuteFilter(OIDNFilter filter);
211
212#if defined(__cplusplus)
213}
214#endif
215