ocl/
lib.rs

1//! # [![](https://img.shields.io/crates/v/ocl.svg)](https://crates.io/crates/ocl) | [GitHub](https://github.com/cogciprocate/ocl)
2//!
3//! Rust implementation of the [OpenCL&trade; API].
4//!
5//! Some versions of this documentation are built from development branches
6//! and may differ slightly between what is on crates.io and the master
7//! branch. See the [repo page](https://github.com/cogciprocate/ocl) for links
8//! to both versions.
9//!
10//! Please report unclear documentation or places where examples would be
11//! appreciated by filing an [issue].
12//!
13//!
14//! ## Foundations
15//!
16//! For lower level interfaces and to use OpenCL features that have not yet
17//! been implemented on the `standard` (high-level) interface types, see the
18//! [`ocl-core`] and [`cl-sys`] crates.
19//!
20//!
21//! ## Help Wanted
22//!
23//! Please request or help complete any functionality you may need by filing
24//! an [issue] or creating a [pull
25//! request](https://github.com/cogciprocate/ocl/pulls).
26//!
27//! Keep an eye out for places where examples would be useful and let us know!
28//!
29//!
30//! ## Feedback appreciated
31//!
32//! Suggestions and nitpicks are most welcome. Don't hesitate to file an
33//! [issue] just to offer constructive criticism.
34//!
35//!
36//! <br/>
37//! *“`OpenCL` and the `OpenCL` logo are trademarks of Apple Inc. used by permission by Khronos.”*
38//!
39//!
40//! [OpenCL&trade; API]: https://www.khronos.org/registry/OpenCL/
41//! [issue]: https://github.com/cogciprocate/ocl/issues
42//! [`ocl-core`]: https://github.com/cogciprocate/ocl-core
43//! [`cl-sys`]: https://github.com/cogciprocate/cl-sys
44//! [`Result`]: /ocl/ocl/type.Result.html
45//! [examples]: https://github.com/cogciprocate/ocl/tree/master/examples
46
47#![doc(html_root_url = "https://docs.rs/ocl/0.19.7")]
48
49// #![warn(missing_docs)]
50
51extern crate futures;
52extern crate num_traits;
53pub extern crate ocl_core;
54
55pub use ocl_core as core;
56
57pub mod r#async;
58pub mod error;
59mod standard;
60#[cfg(test)]
61mod tests;
62
63pub use self::r#async::{
64    FutureMemMap, FutureReadGuard, FutureWriteGuard, MemMap, ReadGuard, RwVec, WriteGuard,
65};
66pub use self::standard::{
67    Buffer, BufferCmdError, Context, Device, Event, EventArray, EventList, Extensions, Image,
68    Kernel, Platform, ProQue, Program, Queue, Sampler, SpatialDims,
69};
70#[doc(no_inline)]
71pub use crate::core::ffi;
72#[doc(no_inline)]
73pub use crate::core::util;
74pub use crate::core::Error as OclCoreError;
75#[doc(no_inline)]
76pub use crate::core::{
77    CommandQueueProperties, DeviceType, MapFlags, MemFlags, OclPrm, OclScl, OclVec,
78};
79pub use crate::error::{Error, Result};
80
81pub mod prm {
82    //! OpenCL scalar and vector primitive types.
83    //!
84    //! Rust primitives may have subtly different behaviour than OpenCL
85    //! primitives within kernels. Wrapping is one example of this. Scalar
86    //! integers within Rust may do overflow checks where in the kernel they
87    //! do not. Therefore OpenCL-compatible implementations of each of the
88    //! types are provided so that host and device side operations can be
89    //! perfectly consistent.
90    //!
91    //! The `cl_...` (`cl_uchar`, `cl_int`, `cl_float`, etc.) types are simple
92    //! aliases of the Rust built-in primitive types and do **not** behave the
93    //! same way that the kernel-side equivalents do. The uppercase-named
94    //! types, on the other hand, (`Uchar`, `Int`, `Float`, etc.) are designed
95    //! to behave identically to their corresponding types within kernels.
96    //!
97    //! Please file an issue if any of the uppercase-named kernel-mimicking
98    //! types deviate from what they should (as they are reasonably new this
99    //! is definitely something to watch out for).
100    //!
101    //! Vector type fields can be accessed using index operations i.e. [0],
102    //! [1], [2] ... etc. Plans for other ways of accessing fields (such as
103    //! `.x()`, `.y()`, `.s0()`, `.s15()`, etc.) will be considered in the
104    //! future (pending a number of additions/stabilizations to the Rust
105    //! language). Create an issue if you have an opinion on the matter.
106    //!
107    //! [NOTE]: This module may be renamed.
108
109    pub use crate::ffi::{
110        cl_bitfield, cl_bool, cl_char, cl_double, cl_float, cl_half, cl_int, cl_long, cl_short,
111        cl_uchar, cl_uint, cl_ulong, cl_ushort,
112    };
113
114    pub use crate::ffi::{cl_GLenum, cl_GLint, cl_GLuint};
115
116    // Wrapping types. Use these to mimic in-kernel behaviour:
117    pub use crate::core::{
118        Char, Char16, Char2, Char3, Char4, Char8, Double, Double16, Double2, Double3, Double4,
119        Double8, Float, Float16, Float2, Float3, Float4, Float8, Int, Int16, Int2, Int3, Int4,
120        Int8, Long, Long16, Long2, Long3, Long4, Long8, Short, Short16, Short2, Short3, Short4,
121        Short8, Uchar, Uchar16, Uchar2, Uchar3, Uchar4, Uchar8, Uint, Uint16, Uint2, Uint3, Uint4,
122        Uint8, Ulong, Ulong16, Ulong2, Ulong3, Ulong4, Ulong8, Ushort, Ushort16, Ushort2, Ushort3,
123        Ushort4, Ushort8,
124    };
125}
126
127pub mod traits {
128    //! Commonly used traits.
129
130    pub use crate::core::{OclPrm, OclScl, OclVec};
131    pub use crate::standard::{IntoMarker, IntoRawEventArray, MemLen, WorkDims};
132}
133
134pub mod builders {
135    //! Builders and associated settings-related types.
136
137    pub use crate::core::{ContextProperties, ImageDescriptor, ImageFormat};
138    pub use crate::standard::{
139        BufferBuilder, BufferCmd, BufferCmdDataShape, BufferCmdKind, BufferMapCmd, BufferReadCmd,
140        BufferWriteCmd, BuildOpt, ContextBuilder, DeviceSpecifier, ImageBuilder, ImageCmd,
141        ImageCmdKind, KernelBuilder, KernelCmd, ProQueBuilder, ProgramBuilder,
142    };
143    pub use crate::standard::{ClNullEventPtrEnum, ClWaitListPtrEnum};
144    // #[cfg(not(release))] pub use standard::BufferTest;
145}
146
147pub mod flags {
148    //! Bitflags for various parameter types.
149
150    pub use crate::core::{
151        // cl_command_queue_properties - bitfield
152        CommandQueueProperties,
153        // cl_device_affinity_domain
154        DeviceAffinityDomain,
155        // cl_device_exec_capabilities - bitfield
156        DeviceExecCapabilities,
157        // cl_device_fp_config - bitfield
158        DeviceFpConfig,
159        // cl_device_type - bitfield
160        DeviceType,
161        // cl_kernel_arg_type_qualifer
162        KernelArgTypeQualifier,
163        // cl_map_flags - bitfield
164        MapFlags,
165        // cl_mem_flags - bitfield
166        MemFlags,
167        // cl_mem_migration_flags - bitfield
168        MemMigrationFlags,
169        // cl_program_binary_type
170        ProgramBinaryType,
171        DEVICE_AFFINITY_DOMAIN_L1_CACHE,
172        DEVICE_AFFINITY_DOMAIN_L2_CACHE,
173        DEVICE_AFFINITY_DOMAIN_L3_CACHE,
174        DEVICE_AFFINITY_DOMAIN_L4_CACHE,
175        DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE,
176        DEVICE_AFFINITY_DOMAIN_NUMA,
177        DEVICE_TYPE_ACCELERATOR,
178        DEVICE_TYPE_ALL,
179        DEVICE_TYPE_CPU,
180        DEVICE_TYPE_CUSTOM,
181        DEVICE_TYPE_DEFAULT,
182        DEVICE_TYPE_GPU,
183        EXEC_KERNEL,
184        EXEC_NATIVE_KERNEL,
185        FP_CORRECTLY_ROUNDED_DIVIDE_SQRT,
186        FP_DENORM,
187        FP_FMA,
188        FP_INF_NAN,
189        FP_ROUND_TO_INF,
190        FP_ROUND_TO_NEAREST,
191        FP_ROUND_TO_ZERO,
192        FP_SOFT_FLOAT,
193        KERNEL_ARG_TYPE_CONST,
194        KERNEL_ARG_TYPE_NONE,
195        KERNEL_ARG_TYPE_RESTRICT,
196        KERNEL_ARG_TYPE_VOLATILE,
197        MAP_READ,
198        MAP_WRITE,
199        MAP_WRITE_INVALIDATE_REGION,
200        MEM_ALLOC_HOST_PTR,
201        MEM_COPY_HOST_PTR,
202        MEM_HOST_NO_ACCESS,
203        MEM_HOST_READ_ONLY,
204        MEM_HOST_WRITE_ONLY,
205        MEM_READ_ONLY,
206        MEM_READ_WRITE,
207        MEM_USE_HOST_PTR,
208        MEM_WRITE_ONLY,
209        MIGRATE_MEM_OBJECT_CONTENT_UNDEFINED,
210        MIGRATE_MEM_OBJECT_HOST,
211        PROGRAM_BINARY_TYPE_COMPILED_OBJECT,
212        PROGRAM_BINARY_TYPE_EXECUTABLE,
213        PROGRAM_BINARY_TYPE_LIBRARY,
214        PROGRAM_BINARY_TYPE_NONE,
215        QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE,
216        QUEUE_PROFILING_ENABLE,
217    };
218}
219
220pub mod enums {
221    //! Enumerators for settings and information requests.
222
223    pub use crate::standard::{BufferCmdDataShape, BufferCmdKind, DeviceSpecifier, WriteSrc};
224
225    // API enums.
226    pub use crate::core::{
227        AddressingMode, BufferCreateType, Cbool, ChannelType, CommandExecutionStatus,
228        CommandQueueInfo, CommandType, ContextInfo, ContextInfoOrPropertiesPointerType,
229        ContextProperty, DeviceInfo, DeviceLocalMemType, DeviceMemCacheType,
230        DevicePartitionProperty, EventInfo, FilterMode, ImageChannelDataType, ImageChannelOrder,
231        ImageInfo, KernelArgAccessQualifier, KernelArgAddressQualifier, KernelArgInfo, KernelInfo,
232        KernelWorkGroupInfo, MemInfo, MemObjectType, PlatformInfo, Polling, ProfilingInfo,
233        ProgramBuildInfo, ProgramBuildStatus, ProgramInfo, SamplerInfo,
234    };
235
236    // Custom enums.
237    pub use crate::core::{
238        ArgVal, CommandQueueInfoResult, ContextInfoResult, ContextPropertyValue, DeviceInfoResult,
239        EventInfoResult, ImageInfoResult, KernelArgInfoResult, KernelInfoResult,
240        KernelWorkGroupInfoResult, MemInfoResult, PlatformInfoResult, ProfilingInfoResult,
241        ProgramBuildInfoResult, ProgramInfoResult, SamplerInfoResult,
242    };
243
244    // Error status.
245    pub use crate::core::Status;
246}
ocl/lib.rs

ocl/
lib.rs
