For now more than 20 years, Blender has been communicating with the host
operating system through the GHOST module. At the time of its creation,
Blender was still mostly written in C. As GHOST relied on C++ virtual
inheritance to define abstract interfaces that are then implemented for
each operating system, a C API had to be put in place to allow calling
of such C++ functions from C, using opaque void pointer types to hold
references to the abstract C++ interface types.
Over the years, with Blender transitioning to C++, the C interface has
become almost completely obsolete, hard to maintain, and is a common
source of confusion and mistakes. With every GHOST method having to be
implemented both in the abstract interface, common base class, OS
specific implementation *and* in the C-API, to then be called from C++
through opaque handles, maintenance and expansion of this system has
become needlessly difficult.
In response to this problem, this PR refactors the GHOST module
internals and the Blender calling code (in the WM, XR, GPU, and general
OS dependent modules) to directly use and call the GHOST C++ class
interfaces methods. Making for a simpler, cleaner and less error prone
usage of the module. As well as providing better insight, IDE support
and understanding of the module functionalities, and removing the need
for opaque handle types and void pointers casting.
Part of the 2025 Platform & Builds Code Quality Project (#151316)
## Main Changes
### Removal of opaque types and port of GHOST Types to C++
The GHOST opaque type handles
(`GHOST_SystemHandle`, `GHOST_WindowHandle`, etc..) were removed in
favor of directly accessing using and accessing their parent interface
class. In addition to this, the main `GHOST_Types.h` header file was
refactored to C++ (and renamed to `.hh`), dropping use of `typedef` for
struct, enum and type alias and replacing them with direct C++ type
definition and `using` declaration, as well as generally cleaning up
the file from now outdated macros.
### Removal of the GHOST C-API interface, and port of calling code to
C++ API
The GHOST C-API interface (GHOST_C-api.h / GHOST_C-api.cc) and GHOST
Path API (GHOST_Path-api.hh / GHOST_Path-api.cc) were removed in favor
of directly using the GHOST interface class in the Blender calling
code, making for a simpler and clearer API, allowing for clear and
limited GHOST header includes, and generally simplifying the code. Some
example of the new C++ API include (before/after):
In general, throughout the code, number of casting is reduced. For
example, in the WM code, a single `GHOST_IWindow *ghost_window` object
can be created from `win->runtime->ghostwin` and be reused in a
function, rather than casting the handle each time:
In addition, certain C++ objects, such as GHOST_Rects, can be directly
instantiated instead of being heap allocated:
### Replacement of void pointers in GPU backend code in favor GHOST
interface pointer types
With GHOST Types now being directly instantiable from within Blender
code, the GPU backend code was improved in favor of replacing `void *`
types referencing the GHOST graphic context with actual
`GHOST_IContext *` interface pointer types, improving both type safety,
general readability and removing the need for casting back and forth.
See changes in `source/blender/gpu`.
### Conservation of the GHOST XR API
As the XR part of the GHOST C-API didn't only provide opaque handle and
C++ function calling, but also XR error handling via
`GHOST_XR_CAPI_CALL{_RET}` macros, this part of the C-API was preserved
in a new sub, XR specific API, exposed in the new `GHOST_Xr-api.hh`
header and implemented in the existing `GHOST_Xr.cc` file. Following
the rest of the refactor, the functions definition and prototypes were
ported from using opaques `GHOST_XrContextHandle` to
`GHOST_IXrContext *` pointer types.
### Removal of legacy GHOST OpenGL based tests
In the GHOST module source tree, a `test` folder remained containing old
tests dating back from the initial Git commit of ~2002. As these files
have to be manually compiled and ran as a separate CMake target, are
well outside our standard testing framework and code style, have
outdated coverage, and mostly rely on pure OpenGL and now unsupported
OpenGL code. The decision was made to remove them rather than uselessly
port them to the C++ API. A possible future quality task could then be
to re-implement proper, modern GHOST tests.
*NOTE: See PR for additional API usage before/after examples.*
Pull Request: https://projects.blender.org/blender/blender/pulls/151792
This change removes the need to to carefully pair MEM_mallocN/MEM_new_for_free
with MEM_freeN and MEM_new with MEM_delete. Instead all function are now
variations of MEM_new and MEM_delete.
* MEM_new_for_free -> MEM_new
* MEM_mallocN -> MEM_new_uninitialized
* MEM_callocN -> MEM_new_zeroed
* MEM_freeN -> MEM_delete (for typed pointers)
* MEM_freeN -> MEM_delete_void (for void pointers)
* MEM_reallocN -> MEM_realloc_uninitialized
* MEM_recallocN -> MEM_realloc_zeroed
* MEM_dupallocN -> MEM_new (when possible)
* MEM_dupallocN -> MEM_dupalloc (for typed pointers)
* MEM_dupallocN -> MEM_dupalloc_void (for void pointers)
The MEM_malloc and MEM_calloc functions were renamed to make it clear that
they should be paired with MEM_delete and to clarify what they do.
The compiler will emit an error if MEM_delete or MEM_delete_void is used on
the wrong pointer type. However a remaining risk is casting a MEM_new allocation
with a non-trivial destructor to a void pointer (which is the same as before). This is
why MEM_delete_void and MEM_dupalloc_void exist as a separate functions,
to identify legacy code that has this risk and should be eliminated over time.
Note that MEM_new_array only supports trivially destructible types. This
avoids the need for an equivalent of the delete [] operator and the associated
mistakes that can be made. Instead MEM_delete can be used for everything. For
non-trivial types, data structures like Vector should be used instead.
MEM_dupalloc is now also more type safe. As before it is only supported on
trivially copyable types, and this is now enforced through static asserts to
prevent mistakes. It is also templated to remove the need for casts.
Pull Request: https://projects.blender.org/blender/blender/pulls/151387
- Mainly avoiding the `ui::UI_*` repetition, removing naming redundancy
- I skipped the "uiDefBut" style functions, those can be handled later
- "uiTemplate" functions are moved to snake case
- "GetThemeColor" functions are still not snake case, that's a next step
- I renamed "but" to "button" for one group of functions
Pull Request: https://projects.blender.org/blender/blender/pulls/151193
`GHOST_SwapWindowBuffers` doesn't fit well when using swapchains. In
that case an approach where swap chain images are acquired and released
would map better. This PR introduces `GHOST_SwapWindowBufferAcquire`
and `GHOST_SwapWindowBufferRelease` to be more in line with vulkan swap
chains.
Previous implementation would first record all GPU commands based on
the last used swap chain. In case a swapchain needed to be recreated
(window resize, move to other monitor) the recorded commands would
not match the swap chain and could lead to artifacts.
OpenGL only implements the release functions as they don't
have a mechanism to acquire a swap chain image. (Need to validate with
the Metal API how this is working and adapt is needed).
Currently when starting blender on a HDR capable display the first frame
would be based on an sRGB surface and presented on an extended RGB
(or other) surface. As these don't match the first frame could be incorrect and
also lead to UBs as another surface is expected.
Pull Request: https://projects.blender.org/blender/blender/pulls/145728
Some mice have an additional horizontal scroll wheel. This patch adds support
for receiving such events. By default it is used to scroll 2D editors left and right.
I originally developed this because I was missing it in the spreadsheet, but it
seems to be useful in many other editors too.
It's supported on Linux (Wayland), Windows and macos.
Pull Request: https://projects.blender.org/blender/blender/pulls/138758
The GHOST_DisplayManager and its implementations are for the most part
unmaintained and almost completely unused in all backends. To clean
things up, and avoid any confusion about how displays are handled in
each respective GHOST backend, this PR completely removes the GHOST
Display Manager, and move the few remaining logic it still held directly
to the corresponding backends.
The backends that were modified (apart from removing the display manager
initialization call from their init) are:
- Win32: `GHOST_SystemWin32::getNumDisplays()` was calling
`m_displayManager->getNumDisplays`, the underlying system metric call
(`GetSystemMetrics(SM_CMONITORS)`) was substituted in place.
- SDL: `GHOST_SystemSDL::createWindow` was calling
`GHOST_DisplayManagerSDL::getCurrentDisplayModeSDL` which returned its
`m_mode` data member by reference. Since none of the
`GHOST_DisplayManagerSDL` member function that modified this data member
were ever called, the variable `memset` initialization call was
substituted in place from the `DisplayManagerSDL` constructor
Pull Request: https://projects.blender.org/blender/blender/pulls/138066
Previously spell checker ignored text in single quotes however this
meant incorrect spelling was ignored in text where it shouldn't have
been.
In cases single quotes were used for literal strings
(such as variables, code & compiler flags),
replace these with back-ticks.
In cases they were used for UI labels,
replace these with double quotes.
In cases they were used to reference symbols,
replace them with doxygens symbol link syntax (leading hash).
Apply some spelling corrections & tweaks (for check_spelling_* targets).
Remove full-screen support from GHOST API's.
Note that this only had back-end implements for X11 and WIN32.
This was last used for the Game Engine to run games full-screen,
removing as it's unused and it doesn't seem likely to be used in the
future.
This doesn't impact making Blender full-screen from the window menu
which uses a window decoration setting.
Ref: !137050
This is because sse2neon.h might be used to emulate SSE intrinsics
on ARM64 architecture, and it uses some preprocessor which is not
available for C language when using MSVC.
The old-style math file math_matrix.c uses this header, so needed
to become C++. Simple rename did not work since there is a new math
utility math_matrix.cc exists. Following some existing convention
the math_matrix.c is renamed to math_matrix_c.cc. Eventually all the
code should switch to use C++ style math, and the C style removed,
so it seems reasonable to not mix old and new style of API in the
same file.
There should be no functional changes.
Pull Request: https://projects.blender.org/blender/blender/pulls/121335
There are some tragic design flaws with the Microsoft STL
implementation of `std::dequeue`. Unless we implement our
own similar data structure or use an implementation from
another library, the change isn't worth it.
This reverts commit b26cd6a4b9.
This reverts commit cc11ba33d9.
This reverts commit c929d75054.
This reverts commit bd3d5a750d.
GSQueue dates back over 21 years, past the initial git commit. Nowadays
we generally prefer to use data structures from the C++ standard library
or our own C++ data structures. Previous commits replaced this container
with `std::queue` in a few areas. Now it is unused and can be removed.
It's possible for there to be no outputs under Wayland
(when unplugging monitors for e.g.) so this must be accounted for.
Also avoid calculating the window position when the GHOST backend
doesn't support window positions (which is the case for Wayland).
Add checks for the SDL backend too, where accessing the
screen & desktop size may fail.
Listing the "Blender Foundation" as copyright holder implied the Blender
Foundation holds copyright to files which may include work from many
developers.
While keeping copyright on headers makes sense for isolated libraries,
Blender's own code may be refactored or moved between files in a way
that makes the per file copyright holders less meaningful.
Copyright references to the "Blender Foundation" have been replaced with
"Blender Authors", with the exception of `./extern/` since these this
contains libraries which are more isolated, any changed to license
headers there can be handled on a case-by-case basis.
Some directories in `./intern/` have also been excluded:
- `./intern/cycles/` it's own `AUTHORS` file is planned.
- `./intern/opensubdiv/`.
An "AUTHORS" file has been added, using the chromium projects authors
file as a template.
Design task: #110784
Ref !110783.
* opengl_context -> system_gpu_context. This is the operating system OpenGL,
Metal or Vulkan context provided by GHOST.
* gpu_context -> blender_gpu_context. This is the GPUContext provided by
the Blender GPU module, which wraps the GHOST context and adds some state.
* Various functions create/destroy/enable/disable both contexts, these have
just gpu_context in the name now.
Pull Request: https://projects.blender.org/blender/blender/pulls/108723
The goal is to solve confusion of the "All rights reserved" for licensing
code under an open-source license.
The phrase "All rights reserved" comes from a historical convention that
required this phrase for the copyright protection to apply. This convention
is no longer relevant.
However, even though the phrase has no meaning in establishing the copyright
it has not lost meaning in terms of licensing.
This change makes it so code under the Blender Foundation copyright does
not use "all rights reserved". This is also how the GPL license itself
states how to apply it to the source code:
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software ...
This change does not change copyright notice in cases when the copyright
is dual (BF and an author), or just an author of the code. It also does
mot change copyright which is inherited from NaN Holding BV as it needs
some further investigation about what is the proper way to handle it.
For example
```
OIIOOutputDriver::~OIIOOutputDriver()
{
}
```
becomes
```
OIIOOutputDriver::~OIIOOutputDriver() {}
```
Saves quite some vertical space, which is especially handy for
constructors.
Pull Request: https://projects.blender.org/blender/blender/pulls/105594
Add command line argument to switch gpu backend. Add `--gpu-backend` option to
override the gpu backend selected by Blender.
Values for this option that will be available in releases for now are:
* opengl: Force blender to select OpenGL backend.
During development and depending on compile options additional values can exist:
* metal: Force Blender to select Metal backend.
When this option isn't provided the internal logic for GPU backend selection will be used.
Note that this is at the time of writing the same as always selecting the opengl backend.
Reviewed By: fclem, brecht, MichaelPW
Differential Revision: https://developer.blender.org/D16297
MTLContext provides functionality for command encoding, binding management and graphics device management. MTLImmediate provides simple draw enablement with dynamically encoded data. These draws utilise temporary scratch buffer memory to provide minimal bandwidth overhead during workload submission.
This patch also contains empty placeholders for MTLBatch and MTLDrawList to enable testing of first pixels on-screen without failure.
The Metal API also requires access to the GHOST_Context to ensure the same pre-initialized Metal GPU device is used by the viewport. Given the explicit nature of Metal, explicit control is also needed over presentation, to ensure correct work scheduling and rendering pipeline state.
Authored by Apple: Michael Parkin-White
Ref T96261
(The diff is based on 043f59cb3b)
Reviewed By: fclem
Differential Revision: https://developer.blender.org/D15953
This cleans up the OpenGL build flags and linking.
It additionally also removes some dead code.
One of these dead code paths is WITH_X11_ALPHA which actually never was
active even with the build flag on. The call to use this was never
called because the default initializer for GHOST was set to have it off
per default. Nothing called this function with a boolean value to enable it.
These cleanups are needed to support true headless OpenGL rendering.
Without these cleanups libepoxy will fail to load the correct OpenGL
Libraries as we have already linked them to the blender binary.
Reviewed By: Brecht, Campbell, Jeroen
Differential Revision: http://developer.blender.org/D15554
With libepoxy we can choose between EGL and GLX at runtime, as well as
dynamically open EGL and GLX libraries without linking to them.
This will make it possible to build with Wayland, EGL, GLVND support while
still running on systems that only have X11, GLX and libGL. It also paves
the way for headless rendering through EGL.
libepoxy is a new library dependency, and is included in the precompiled
libraries. GLEW is no longer a dependency, and WITH_SYSTEM_GLEW was removed.
Includes contributions by Brecht Van Lommel, Ray Molenkamp, Campbell Barton
and Sergey Sharybin.
Ref T76428
Differential Revision: https://developer.blender.org/D15291
The `ascii` member was only kept for historic reason as some platforms
didn't support utf8 when it was first introduced.
Remove the `ascii` struct members since many checks used this as a
fall-back for utf8_buf not being set which isn't needed.
There are a few cases where it's convenient to access the ASCII value
of an event (or nil) so a function has been added to do that.
*Details*
- WM_event_utf8_to_ascii() has been added for the few cases an events
ASCII value needs to be accessed, this just avoids having to do
multi-byte character checks in-line.
- RNA Event.ascii remains, using utf8_buf[0] for single byte characters.
- GHOST_TEventKeyData.ascii has been removed.
- To avoid regressions non-ASCII Latin1 characters from GHOST are
converted into multi-byte UTF8, when building X11 without
XInput & X_HAVE_UTF8_STRING it seems like could still occur.
