CONTRIBUTING.md

Contributing to Intel® GPU Compute Samples

Thanks for your time! Below you can find guidelines for contributing to the project.

Pull Requests

We are open for all kind of contributions including bug fixes, enhancements and documentation. Before creating a pull request please make sure that:

• Your changes can be successfully built.
• All tests are passing.
• Source code is formatted using clang-format with the defined style.

Issues and enhancements

All bug reports and feature requests are welcomed and should be reported to the issue tracker. Even more welcomed are pull requests fixing these issues.

Testing

Testing instructions can be found in the README.

Directory structure

• build - build artifacts. Directory should be created by a user.
• cmake - custom CMake scripts.
• compute_samples - source code.
• compute_samples/applications - source code of the applications.
• compute_samples/core - source code of the core modules.
• docs - documentation and other resources about the project.
• mediadata - directory with media data. It contains merged internal and external media data. This way applications don't need to know whether a media file is external or internal.
• mediadata/external - media files downloaded from external sources.
• mediadata/internal - small media files stored in the repository.
• third_party - external dependencies.

How to add a new application?

In order to automatically create an application from a template please use scripts/generate_target.py with the following command line python generate_target.py your_app.

If you want to manually prepare an application from scratch then please follow the instruction below.

1. Prepare directory structure:

   1. Create directory for your_app in compute_samples/applications.
   2. Create include/your_app directories for public header files in compute_samples/applications/your_app.
   3. Create src directory for source files and private headers in compute_samples/applications/your_app.
   4. Create test directory for test files in compute_samples/applications/your_app.
   5. All files which are not a source code e.g. video files should be placed in mediadata/internal directory or if they are too big they should be downloaded into mediadata/external directory.

   Example directory structure for compute_samples/applications/your_app:

   ├── CMakeLists.txt
   ├── include
   │   └── your_app
   │       └── your_app.hpp
   ├── your_app_kernel.cl
   ├── src
   │   └── your_app.cpp
   │   └── main.cpp
   └── test
       ├── main.cpp
       ├── your_app_integration_tests.cpp
       ├── your_app_system_tests.cpp
       └── your_app_unit_tests.cpp
   

2. Prepare CMake:

   1. Add subdirectory with your_app to the compute_samples/applications/CMakeLists.txt.

   2. Create a CMakeLists.txt file in compute_samples/applications/your_app.

      1. Create your_app_lib library by using add_application_library function.
      2. Link any required libraries with target_link_libraries function.
      3. Create your_app binary by using add_application function.
      4. Create your_app_tests binary by using add_application_test function.
      5. Add OpenCL kernels to the library with add_kernels function.
      6. Install kernels together with the application and tests by calling install_kernels function.
      7. If necessary install any other resources with install_resources function.

      Example CMakeLists.txt:

      #
      # Copyright(c) 2018 Intel Corporation
      #
      # Permission is hereby granted, free of charge, to any person obtaining a copy
      # of this software and associated documentation files (the "Software"), to deal
      # in the Software without restriction, including without limitation the rights
      # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
      # copies of the Software, and to permit persons to whom the Software is
      # furnished to do so, subject to the following conditions:
      #
      # The above copyright notice and this permission notice shall be included in
      # all copies or substantial portions of the Software.
      #
      # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
      # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
      # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
      # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
      # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
      # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
      # SOFTWARE.
      #
      
      add_application_library(your_app
          SOURCE
          "include/your_app/your_app.hpp"
          "src/your_app.cpp"
      )
      target_link_libraries(your_app_lib
          PUBLIC
          compute_samples::image
          Boost::program_options
      )
      add_kernels(your_app_lib "your_app_kernel.cl")
      
      add_application(your_app
          SOURCE
          "src/main.cpp"
      )
      install_kernels(your_app "your_app_kernel.cl")
      install_resources(your_app FILES "${MEDIA_DIRECTORY}/png/your_app_media.png")
      
      add_application_test(your_app
          SOURCE
          "test/main.cpp"
          "test/your_app_unit_tests.cpp"
          "test/your_app_integration_tests.cpp"
          "test/your_app_system_tests.cpp"
      )
      install_kernels(your_app_tests "your_app_kernel.cl")
      install_resources(your_app_tests
          FILES
          "${MEDIA_DIRECTORY}/png/test_input.png"
          "${MEDIA_DIRECTORY}/png/test_reference.png"
      )

3. Prepare the source code:

   1. Create YourApplication class which is derived from Application interface available in application/application.hpp header.
   2. Implement all methods required by the Application interface e.g. Application::run_implementation.
   3. Add tests using Google Test to the compute_samples/applications/your_app/test directory.

Logging levels

Logging levels are a way of grouping certain types of messages printed by an application. Proper usage of all levels may greatly increase readability of produced logs and maintainability of the application. That's why we strongly encourage you to get familiar with all available logging levels described below:

• Fatal - reserved for critical failures when the application is about to abort.
• Error - describes serious issues which should be further investigated. Such situations often occur within a single unit and the application as a whole may handle it gracefully.
• Warning - indicates any abnormalities that occurred but were properly handled by the application.
• Information - tells users what the application is currently doing; this is the default.
• Debug - adds additional information and contexts to the messages.
• Trace - the most fine-grained messages, reserved for purely diagnostic purposes.

Naming conventions

We are using the following naming conventions:

• Class - UpperCamelCase - class MyClass
• Class data member - snake_case_with_suffix - MyClass::my_class_data_member_
• Struct - UpperCamelCase - struct MyStruct
• Struct data member - snake_case - MyStruct::my_struct_data_member
• Function - snake_case - void my_function()
• Variable - snake_case - int my_variable
• Constant - snake_case - const int my_constant
• Enum - snake_case - enum class my_enum
• Enum member - snake_case - my_enum::my_enum_member
• Namespace - snake_case - namespace my_namespace
• Macro - CAPITALIZED_WITH_UNDERSCORES - #define MY_MACRO
• File - snake_case - my_file.cpp
• Module - snake_case - my_module
• Test - UpperCamelCase - TEST(MyTestCase, MyTest)