{"id":13809684,"url":"https://github.com/kenba/opencl3","last_synced_at":"2025-12-12T15:18:07.184Z","repository":{"id":41535467,"uuid":"325826935","full_name":"kenba/opencl3","owner":"kenba","description":"A Rust implementation of the Khronos OpenCL 3.0 API.","archived":false,"fork":false,"pushed_at":"2025-04-19T10:35:36.000Z","size":531,"stargazers_count":113,"open_issues_count":4,"forks_count":15,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-19T16:14:47.646Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kenba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-12-31T15:31:32.000Z","updated_at":"2025-04-19T10:34:23.000Z","dependencies_parsed_at":"2023-01-31T11:45:53.145Z","dependency_job_id":"924dcf6c-e6a2-4f68-91b2-13a6f4ac558a","html_url":"https://github.com/kenba/opencl3","commit_stats":{"total_commits":159,"total_committers":5,"mean_commits":31.8,"dds":0.09433962264150941,"last_synced_commit":"4619128df954ac3aa1f2af7774c543f3be808b6c"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenba%2Fopencl3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenba%2Fopencl3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenba%2Fopencl3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenba%2Fopencl3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kenba","download_url":"https://codeload.github.com/kenba/opencl3/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254104920,"owners_count":22015565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T02:00:34.396Z","updated_at":"2025-12-12T15:18:07.178Z","avatar_url":"https://github.com/kenba.png","language":"Rust","funding_links":[],"categories":["Frameworks","GPU Programming"],"sub_categories":[],"readme":"# opencl3\n\n[![crates.io](https://img.shields.io/crates/v/opencl3.svg)](https://crates.io/crates/opencl3)\n[![docs.io](https://docs.rs/opencl3/badge.svg)](https://docs.rs/opencl3/)\n[![OpenCL 3.0](https://img.shields.io/badge/OpenCL-3.0-blue.svg)](https://www.khronos.org/registry/OpenCL/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Rust](https://github.com/kenba/opencl3/workflows/Rust/badge.svg)](https://github.com/kenba/opencl3/actions)\n\nA Rust implementation of the Khronos [OpenCL](https://www.khronos.org/registry/OpenCL/) API.\n\n## Description\n\nA relatively simple, object based model of the OpenCL 3.0\n[API](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_API.html).  \nIt is built upon the [cl3](https://crates.io/crates/cl3) crate, which\nprovides a functional interface to the OpenCL [C API](https://github.com/KhronosGroup/OpenCL-Headers/blob/master/CL/cl.h).  \n\n[OpenCL](https://www.khronos.org/opencl/) (Open Computing Language) is framework for general purpose parallel programming across heterogeneous devices including: CPUs, GPUs, DSPs, FPGAs and other processors or hardware accelerators. It is often considered as an open-source alternative to Nvidia's proprietary\nCompute Unified Device Architecture [CUDA](https://developer.nvidia.com/cuda-zone)\nfor performing General-purpose computing on GPUs, see\n[GPGPU](https://en.wikipedia.org/wiki/General-purpose_computing_on_graphics_processing_units).\n\n[OpenCL 3.0](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_API.html)\nis a unified specification that adds little new functionality to previous OpenCL versions.  \nIt specifies that all **OpenCL 1.2** features are **mandatory**, while all\nOpenCL 2.x and 3.0 features are now optional.\n\n### Features\n\nThis library has:\n\n* A simple API, enabling most OpenCL objects to be created with a single function call.\n* Automatic OpenCL resource management using the [Drop trait](https://doc.rust-lang.org/book/ch15-03-drop.html) to implement [RAII](https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization).\n* Support for [directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) OpenCL control flow execution using event wait lists.\n* Support for Shared Virtual Memory (SVM) with an [SvmVec](src/svm.rs) object that can be serialized and deserialized by [serde](https://serde.rs/).\n* Support for OpenCL extensions, see [OpenCL Extensions](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html).\n* Support for multithreading with [Send and Sync](https://doc.rust-lang.org/nomicon/send-and-sync.html) traits.\n\n## Design\n\nThe library is object based with most OpenCL objects represented by rust structs.\nFor example, an OpenCL `cl_device_id` is represented by [Device](src/device.rs) with methods to get information about the device instead of calling `clGetDeviceInfo` with the relevant `cl_device_info` value.  \n\n![OpenCL Context](docs/images/opencl_context_objects.svg)  \n*OpenCL Context Class Diagram*\n\nThe struct methods are simpler to use than their equivalent standalone functions in [cl3](https://github.com/kenba/cl3) because they convert the `InfoType` enum into the correct underlying type returned by the `clGetDeviceInfo` call for the `cl_device_info` value.\n\nNearly all the structs implement the `Drop` trait to release their corresponding\nOpenCL objects. The exceptions are `Platform` and `Device` which don't need to be released. See the crate [documentation](https://docs.rs/opencl3/).\n\nThe API for OpenCL versions and extensions are controlled by Rust features such as \"CL_VERSION_2_0\" and \"cl_khr_gl_sharing\". To enable an OpenCL version, the feature for that version and **all** previous OpenCL versions must be enabled, e.g. for \"CL_VERSION_2_0\"; \"CL_VERSION_1_1\" and \"CL_VERSION_1_2\" must also be enabled.\n\nThe default features are \"CL_VERSION_1_1\", \"CL_VERSION_1_2\" and \"CL_VERSION_2_0\".\n\nRust deprecation warnings are given for OpenCL API functions that are deprecated by an enabled OpenCL version e.g., `clCreateCommandQueue` is deprecated whenever \"CL_VERSION_2_0\" is enabled.\n\n## Use\n\nEnsure that an OpenCL Installable Client Driver (ICD) and the appropriate OpenCL\nhardware driver(s) are installed, see\n[OpenCL Installation](https://github.com/kenba/cl3/tree/main/docs/opencl_installation.md).\n\n`opencl3` supports OpenCL 1.2 and 2.0 ICD loaders by default. If you have an\nOpenCL 2.0 ICD loader then just add the following to your project's `Cargo.toml`:\n\n```toml\n[dependencies]\nopencl3 = \"0.12\"\n```\n\nIf your OpenCL ICD loader supports higher versions of OpenCL then add the\nappropriate features to opencl3, e.g. for an OpenCL 3.0 ICD loader add the\nfollowing to your project's `Cargo.toml` instead:\n\n```toml\n[dependencies.opencl3]\nversion = \"0.12\"\nfeatures = [\"CL_VERSION_2_1\", \"CL_VERSION_2_2\", \"CL_VERSION_3_0\"]\n```\n\nOpenCL extensions and `serde` support can also be enabled by adding their features, e.g.:\n\n```toml\n[dependencies.opencl3]\nversion = \"0.12\"\nfeatures = [\"cl_khr_gl_sharing\", \"cl_khr_dx9_media_sharing\", \"serde\"]\n```\n\nSee the [OpenCL Guide](https://github.com/KhronosGroup/OpenCL-Guide) and [OpenCL Description](https://github.com/kenba/opencl3/tree/main/docs/opencl_description.md) for background on using OpenCL.\n\n## Examples\n\nThere are examples in the [examples](https://github.com/kenba/opencl3/tree/main/examples/) directory.\nThe tests also provide examples of how the crate may be used, e.g. see:\n[platform](https://github.com/kenba/opencl3/tree/main/src/platform.rs),\n[device](https://github.com/kenba/opencl3/tree/main/src/device.rs),\n[context](https://github.com/kenba/opencl3/tree/main/src/context.rs),\n[integration_test](https://github.com/kenba/opencl3/tree/main/tests/integration_test.rs) and\n[opencl2_kernel_test](https://github.com/kenba/opencl3/tree/main/tests/opencl2_kernel_test.rs).\n\nThe library is designed to support events and OpenCL 2 features such as Shared Virtual Memory (SVM) and kernel built-in work-group functions.\nIt also has optional support for `serde` e.g.:\n\n```rust no-run\nconst PROGRAM_SOURCE: \u0026str = r#\"\nkernel void inclusive_scan_int (global int* output,\n                                global int const* values)\n{\n    int sum = 0;\n    size_t lid = get_local_id(0);\n    size_t lsize = get_local_size(0);\n\n    size_t num_groups = get_num_groups(0);\n    for (size_t i = 0u; i \u003c num_groups; ++i)\n    {\n        size_t lidx = i * lsize + lid;\n        int value = work_group_scan_inclusive_add(values[lidx]);\n        output[lidx] = sum + value;\n\n        sum += work_group_broadcast(value, lsize - 1);\n    }\n}\"#;\n\nconst KERNEL_NAME: \u0026str = \"inclusive_scan_int\";\n\n// Create a Context on an OpenCL device\nlet context = Context::from_device(\u0026device).expect(\"Context::from_device failed\");\n\n// Build the OpenCL program source and create the kernel.\nlet program = Program::create_and_build_from_source(\u0026context, PROGRAM_SOURCE, CL_STD_2_0)\n    .expect(\"Program::create_and_build_from_source failed\");\n\nlet kernel = Kernel::create(\u0026program, KERNEL_NAME).expect(\"Kernel::create failed\");\n\n// Create a command_queue on the Context's device\nlet queue = CommandQueue::create_default_with_properties(\n    \u0026context,\n    CL_QUEUE_PROFILING_ENABLE,\n    0,\n)\n.expect(\"CommandQueue::create_default_with_properties failed\");\n\n// The input data\nconst ARRAY_SIZE: usize = 8;\nconst VALUE_ARRAY: \u0026str = \"[3,2,5,9,7,1,4,2]\";\n\n// Create an OpenCL SVM vector\nlet mut test_values = SvmVec::\u003ccl_int\u003e::new(\u0026context);\n\n// Handle test_values if device only supports CL_DEVICE_SVM_COARSE_GRAIN_BUFFER\nif !test_values.is_fine_grained() {\n    // SVM_COARSE_GRAIN_BUFFER needs to know the size of the data to allocate the SVM\n    test_values = SvmVec::\u003ccl_int\u003e::allocate(\u0026context, ARRAY_SIZE).expect(\"SVM allocation failed\");\n    // Map the SVM for a SVM_COARSE_GRAIN_BUFFER\n    unsafe { queue.enqueue_svm_map(CL_BLOCKING, CL_MAP_WRITE, \u0026mut test_values, \u0026[])? };\n    // Clear the SVM for the deserializer\n    test_values.clear();\n}\n\nExtendSvmVec(\u0026mut test_values)\n    .deserialize(\u0026mut deserializer)\n    .expect(\"Error deserializing the VALUE_ARRAY JSON string.\");\n\n// Make test_values immutable\nlet test_values = test_values;\n\n// Unmap test_values if not a CL_MEM_SVM_FINE_GRAIN_BUFFER\nif !test_values.is_fine_grained() {\n    let unmap_test_values_event = unsafe { queue.enqueue_svm_unmap(\u0026test_values, \u0026[])? };\n    unmap_test_values_event.wait()?;\n}\n\n// The output data, an OpenCL SVM vector\nlet mut results =\n    SvmVec::\u003ccl_int\u003e::allocate(\u0026context, ARRAY_SIZE).expect(\"SVM allocation failed\");\n\n// Run the kernel on the input data\nlet sum_kernel_event = unsafe {\n    ExecuteKernel::new(\u0026kernel)\n        .set_arg_svm(results.as_mut_ptr())\n        .set_arg_svm(test_values.as_ptr())\n        .set_global_work_size(ARRAY_SIZE)\n        .enqueue_nd_range(\u0026queue)?\n};\n\n// Wait for the kernel to complete execution on the device\nkernel_event.wait()?;\n\n// Map results if not a CL_MEM_SVM_FINE_GRAIN_BUFFER\nif !results.is_fine_grained() {\n    unsafe { queue.enqueue_svm_map(CL_BLOCKING, CL_MAP_READ, \u0026mut results, \u0026[])? };\n}\n\n// Convert SVM results to json\nlet json_results = serde_json::to_string(\u0026results).unwrap();\nprintln!(\"json results: {}\", json_results);\n\n// Unmap results if not a CL_MEM_SVM_FINE_GRAIN_BUFFER\nif !results.is_fine_grained() {\n    let unmap_results_event = unsafe { queue.enqueue_svm_unmap(\u0026results, \u0026[])? };\n    unmap_results_event.wait()?;\n}\n```\n\nThe example above was taken from:\n[opencl2serde.rs](https://github.com/kenba/opencl3/tree/main/examples/opencl2serde.rs).\n\n## Tests\n\nThe crate contains unit, documentation and integration tests.  \nThe tests run the platform and device info functions (among others) so they\ncan provide useful information about OpenCL capabilities of the system.\n\nIt is recommended to run the tests in single-threaded mode, since some of\nthem can interfere with each other when run multi-threaded, e.g.:\n\n```shell\ncargo test -- --test-threads=1 --show-output\n```\n\nThe integration tests are marked `ignore` so use the following command to\nrun them:\n\n```shell\ncargo test -- --test-threads=1 --show-output --ignored\n```\n\n## Recent changes\n\nThe API has changed considerably since version `0.1` of the library, with the\naim of making the library more consistent and easier to use.\n\n[SvmVec](src/svm.rs) was changed recently to provide support for `serde` deserialization.\nIt also changed in version 0.5.0 to provide better support for\ncoarse grain buffer Shared Virtual Memory now that Nvidia is supporting it,\nsee [Nvidia OpenCL](https://developer.nvidia.com/opencl).\n\nIn version 0.6.0 the Info enums were removed from the underlying [cl3](https://crates.io/crates/cl3) crate and this crate so that data can be read from OpenCL devices in the future using new values that are currently undefined.\n\nIn version 0.8.0 deprecation warnings are given for OpenCL API functions that are deprecated by an enabled OpenCL version e.g., `clCreateCommandQueue` is deprecated whenever \"CL_VERSION_2_0\" is enabled.\n\nIn version 0.9.0 many OpenCL API functions are declared `unsafe` since they may cause undefined behaviour if called incorrectly.\n\nFor information on other changes, see [Releases](RELEASES.md).\n\n## Contribution\n\nIf you want to contribute through code or documentation, the [Contributing](CONTRIBUTING.md) guide is the best place to start. If you have any questions, please feel free to ask.\nJust please abide by our [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## License\n\nLicensed under the Apache License, Version 2.0, as per Khronos Group OpenCL.  \nYou may obtain a copy of the License at: \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e\n\nAny contribution intentionally submitted for inclusion in the work by you shall be licensed  as defined in the Apache-2.0 license above, without any additional terms or conditions, unless you explicitly state otherwise.\n\nOpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenba%2Fopencl3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkenba%2Fopencl3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenba%2Fopencl3/lists"}