From 92288da76e879149179292f90dd2760f587c9132 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Wed, 20 Nov 2019 22:38:49 +0100 Subject: Rename "backend" headers Working on Vulkan clarified what has always been slightly smelly about the design and organization here: not everything that is API specific is really in a "backend" (a PuglBackend). The concrete example is puglGetProcAddress(), which only makes sense for GL and is actually implemented in the "backend" files. Arguably puglGetContext() is also such a thing. So, rename the headers so they can be the place where API-specific things go in general, which happens to include a backend most of the time. The stub is a bit of an exception to this, but whatever. The includes look tidier this way. In place of the old headers are compatibility stubs that just emit a warning and include the new version, which will be maintained for a while. --- pugl/detail/mac.m | 2 +- pugl/detail/mac_cairo.m | 4 +- pugl/detail/mac_gl.m | 4 +- pugl/detail/win.c | 2 +- pugl/detail/win_cairo.c | 2 +- pugl/detail/win_gl.c | 4 +- pugl/detail/x11.c | 2 +- pugl/detail/x11_cairo.c | 2 +- pugl/detail/x11_gl.c | 4 +- pugl/pugl.h | 4 +- pugl/pugl_cairo.h | 42 +++++++++++++++++ pugl/pugl_cairo_backend.h | 23 +--------- pugl/pugl_gl.h | 53 ++++++++++++++++++++++ pugl/pugl_gl_backend.h | 34 +------------- pugl/pugl_stub.h | 113 ++++++++++++++++++++++++++++++++++++++++++++++ pugl/pugl_stub_backend.h | 96 ++------------------------------------- test/pugl_cairo_test.c | 2 +- test/pugl_gl3_test.c | 2 +- test/pugl_print_events.c | 2 +- test/pugl_test.c | 2 +- 20 files changed, 234 insertions(+), 165 deletions(-) create mode 100644 pugl/pugl_cairo.h create mode 100644 pugl/pugl_gl.h create mode 100644 pugl/pugl_stub.h diff --git a/pugl/detail/mac.m b/pugl/detail/mac.m index 7534281..efa4d78 100644 --- a/pugl/detail/mac.m +++ b/pugl/detail/mac.m @@ -24,7 +24,7 @@ #include "pugl/detail/implementation.h" #include "pugl/detail/mac.h" #include "pugl/pugl.h" -#include "pugl/pugl_stub_backend.h" +#include "pugl/pugl_stub.h" #import diff --git a/pugl/detail/mac_cairo.m b/pugl/detail/mac_cairo.m index 1e4149c..6b9f36c 100644 --- a/pugl/detail/mac_cairo.m +++ b/pugl/detail/mac_cairo.m @@ -20,8 +20,8 @@ #include "pugl/detail/implementation.h" #include "pugl/detail/mac.h" -#include "pugl/pugl_cairo_backend.h" -#include "pugl/pugl_stub_backend.h" +#include "pugl/pugl_cairo.h" +#include "pugl/pugl_stub.h" #include diff --git a/pugl/detail/mac_gl.m b/pugl/detail/mac_gl.m index f39c25e..428cc1a 100644 --- a/pugl/detail/mac_gl.m +++ b/pugl/detail/mac_gl.m @@ -20,8 +20,8 @@ #include "pugl/detail/implementation.h" #include "pugl/detail/mac.h" -#include "pugl/pugl_gl_backend.h" -#include "pugl/pugl_stub_backend.h" +#include "pugl/pugl_gl.h" +#include "pugl/pugl_stub.h" #ifndef __MAC_10_10 #define NSOpenGLProfileVersion4_1Core NSOpenGLProfileVersion3_2Core diff --git a/pugl/detail/win.c b/pugl/detail/win.c index d7026ae..9debb6d 100644 --- a/pugl/detail/win.c +++ b/pugl/detail/win.c @@ -21,7 +21,7 @@ #include "pugl/detail/implementation.h" #include "pugl/detail/win.h" #include "pugl/pugl.h" -#include "pugl/pugl_stub_backend.h" +#include "pugl/pugl_stub.h" #include #include diff --git a/pugl/detail/win_cairo.c b/pugl/detail/win_cairo.c index 27765ec..7966b07 100644 --- a/pugl/detail/win_cairo.c +++ b/pugl/detail/win_cairo.c @@ -20,7 +20,7 @@ #include "pugl/detail/types.h" #include "pugl/detail/win.h" -#include "pugl/pugl_cairo_backend.h" +#include "pugl/pugl_cairo.h" #include #include diff --git a/pugl/detail/win_gl.c b/pugl/detail/win_gl.c index d872303..ee3b032 100644 --- a/pugl/detail/win_gl.c +++ b/pugl/detail/win_gl.c @@ -20,8 +20,8 @@ #include "pugl/detail/types.h" #include "pugl/detail/win.h" -#include "pugl/pugl_gl_backend.h" -#include "pugl/pugl_stub_backend.h" +#include "pugl/pugl_gl.h" +#include "pugl/pugl_stub.h" #include diff --git a/pugl/detail/x11.c b/pugl/detail/x11.c index 133436c..9256b2e 100644 --- a/pugl/detail/x11.c +++ b/pugl/detail/x11.c @@ -26,7 +26,7 @@ #include "pugl/detail/types.h" #include "pugl/detail/x11.h" #include "pugl/pugl.h" -#include "pugl/pugl_stub_backend.h" +#include "pugl/pugl_stub.h" #include #include diff --git a/pugl/detail/x11_cairo.c b/pugl/detail/x11_cairo.c index 1c7df6e..523a569 100644 --- a/pugl/detail/x11_cairo.c +++ b/pugl/detail/x11_cairo.c @@ -21,7 +21,7 @@ #include "pugl/detail/types.h" #include "pugl/detail/x11.h" #include "pugl/pugl.h" -#include "pugl/pugl_cairo_backend.h" +#include "pugl/pugl_cairo.h" #include #include diff --git a/pugl/detail/x11_gl.c b/pugl/detail/x11_gl.c index a881510..d325f9d 100644 --- a/pugl/detail/x11_gl.c +++ b/pugl/detail/x11_gl.c @@ -21,8 +21,8 @@ #include "pugl/detail/types.h" #include "pugl/detail/x11.h" #include "pugl/pugl.h" -#include "pugl/pugl_gl_backend.h" -#include "pugl/pugl_stub_backend.h" +#include "pugl/pugl_gl.h" +#include "pugl/pugl_stub.h" #include #include diff --git a/pugl/pugl.h b/pugl/pugl.h index fa75878..d4f079e 100644 --- a/pugl/pugl.h +++ b/pugl/pugl.h @@ -719,8 +719,8 @@ typedef struct PuglBackendImpl PuglBackend; This needs to be called once before creating the window to set the graphics backend. There are two backend accessors included with pugl: - puglGlBackend() and puglCairoBackend(), declared in pugl_gl_backend.h and - pugl_cairo_backend.h, respectively. + puglGlBackend() and puglCairoBackend(), declared in pugl_gl.h and + pugl_cairo.h, respectively. */ PUGL_API PuglStatus puglSetBackend(PuglView* view, const PuglBackend* backend); diff --git a/pugl/pugl_cairo.h b/pugl/pugl_cairo.h new file mode 100644 index 0000000..001bca9 --- /dev/null +++ b/pugl/pugl_cairo.h @@ -0,0 +1,42 @@ +/* + Copyright 2012-2019 David Robillard + + Permission to use, copy, modify, and/or distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +*/ + +/** + @file pugl_cairo.h Declaration of Cairo backend accessor. +*/ + +#ifndef PUGL_PUGL_CAIRO_H +#define PUGL_PUGL_CAIRO_H + +#include "pugl/pugl.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + Cairo graphics backend accessor. + + Pass the return value to puglInitBackend() to draw to a view with Cairo. +*/ +PUGL_API const PuglBackend* +puglCairoBackend(void); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif // PUGL_PUGL_CAIRO_H diff --git a/pugl/pugl_cairo_backend.h b/pugl/pugl_cairo_backend.h index 9e1a046..3f8cec3 100644 --- a/pugl/pugl_cairo_backend.h +++ b/pugl/pugl_cairo_backend.h @@ -14,29 +14,10 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/** - @file pugl_cairo_backend.h Declaration of Cairo backend accessor. -*/ - #ifndef PUGL_PUGL_CAIRO_BACKEND_H #define PUGL_PUGL_CAIRO_BACKEND_H -#include "pugl/pugl.h" - -#ifdef __cplusplus -extern "C" { -#endif - -/** - Cairo graphics backend accessor. - - Pass the return value to puglInitBackend() to draw to a view with Cairo. -*/ -PUGL_API const PuglBackend* -puglCairoBackend(void); - -#ifdef __cplusplus -} /* extern "C" */ -#endif +#warning "This header is deprecated, use pugl/pugl_cairo.h instead." +#include "pugl/pugl_cairo.h" #endif // PUGL_PUGL_CAIRO_BACKEND_H diff --git a/pugl/pugl_gl.h b/pugl/pugl_gl.h new file mode 100644 index 0000000..7789116 --- /dev/null +++ b/pugl/pugl_gl.h @@ -0,0 +1,53 @@ +/* + Copyright 2012-2019 David Robillard + + Permission to use, copy, modify, and/or distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +*/ + +/** + @file pugl_gl.h OpenGL-specific API. +*/ + +#ifndef PUGL_PUGL_GL_H +#define PUGL_PUGL_GL_H + +#include "pugl/pugl.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + OpenGL extension function. +*/ +typedef void (*PuglGlFunc)(void); + +/** + Return the address of an OpenGL extension function. +*/ +PUGL_API PuglGlFunc +puglGetProcAddress(const char* name); + +/** + OpenGL graphics backend. + + Pass the return value to puglInitBackend() to draw to a view with OpenGL. +*/ +PUGL_API const PuglBackend* +puglGlBackend(void); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif // PUGL_PUGL_GL_H diff --git a/pugl/pugl_gl_backend.h b/pugl/pugl_gl_backend.h index c0e5b08..e1b9a15 100644 --- a/pugl/pugl_gl_backend.h +++ b/pugl/pugl_gl_backend.h @@ -14,40 +14,10 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/** - @file pugl_gl_backend.h Declaration of OpenGL backend accessor. -*/ - #ifndef PUGL_PUGL_GL_BACKEND_H #define PUGL_PUGL_GL_BACKEND_H -#include "pugl/pugl.h" - -#ifdef __cplusplus -extern "C" { -#endif - -/** - OpenGL extension function. -*/ -typedef void (*PuglGlFunc)(void); - -/** - Return the address of an OpenGL extension function. -*/ -PUGL_API PuglGlFunc -puglGetProcAddress(const char* name); - -/** - OpenGL graphics backend. - - Pass the return value to puglInitBackend() to draw to a view with OpenGL. -*/ -PUGL_API const PuglBackend* -puglGlBackend(void); - -#ifdef __cplusplus -} /* extern "C" */ -#endif +#warning "This header is deprecated, use pugl/pugl_gl.h instead." +#include "pugl/pugl_gl.h" #endif // PUGL_PUGL_GL_BACKEND_H diff --git a/pugl/pugl_stub.h b/pugl/pugl_stub.h new file mode 100644 index 0000000..40d1036 --- /dev/null +++ b/pugl/pugl_stub.h @@ -0,0 +1,113 @@ +/* + Copyright 2019 David Robillard + + Permission to use, copy, modify, and/or distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +*/ + +/** + @file pugl_stub.h Stub backend functions and accessor declaration. +*/ + +#ifndef PUGL_PUGL_STUB_H +#define PUGL_PUGL_STUB_H + +#include "pugl/pugl.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + Stub graphics backend. + + This backend just creates a simple native window without setting up any + portable graphics API. +*/ +PUGL_API +const PuglBackend* +puglStubBackend(void); + +/** + @name Stub backend functions + + Implementations of stub backend functions which do nothing and always return + success. These do not make for a usable backend on their own since the + platform implementation would fail to create a window, but are useful for + other backends to reuse since not all need non-trivial implementations of + every backend function. + + @{ +*/ + +static inline PuglStatus +puglStubConfigure(PuglView* view) +{ + (void)view; + return PUGL_SUCCESS; +} + +static inline PuglStatus +puglStubCreate(PuglView* view) +{ + (void)view; + return PUGL_SUCCESS; +} + +static inline PuglStatus +puglStubDestroy(PuglView* view) +{ + (void)view; + return PUGL_SUCCESS; +} + +static inline PuglStatus +puglStubEnter(PuglView* view, bool drawing) +{ + (void)view; + (void)drawing; + return PUGL_SUCCESS; +} + +static inline PuglStatus +puglStubLeave(PuglView* view, bool drawing) +{ + (void)view; + (void)drawing; + return PUGL_SUCCESS; +} + +static inline PuglStatus +puglStubResize(PuglView* view, int width, int height) +{ + (void)view; + (void)width; + (void)height; + return PUGL_SUCCESS; +} + +static inline void* +puglStubGetContext(PuglView* view) +{ + (void)view; + return NULL; +} + +/** + @} +*/ + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif // PUGL_PUGL_STUB_H diff --git a/pugl/pugl_stub_backend.h b/pugl/pugl_stub_backend.h index 8dba30d..e5aa513 100644 --- a/pugl/pugl_stub_backend.h +++ b/pugl/pugl_stub_backend.h @@ -1,5 +1,5 @@ /* - Copyright 2019 David Robillard + Copyright 2012-2019 David Robillard Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above @@ -14,100 +14,10 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/** - @file pugl_stub_backend.h Stub backend functions and accessor declaration. -*/ - #ifndef PUGL_PUGL_STUB_BACKEND_H #define PUGL_PUGL_STUB_BACKEND_H -#include "pugl/pugl.h" - -#ifdef __cplusplus -extern "C" { -#endif - -/** - Stub graphics backend. - - This backend just creates a simple native window without setting up any - portable graphics API. -*/ -PUGL_API -const PuglBackend* -puglStubBackend(void); - -/** - @name Stub backend functions - - Implementations of stub backend functions which do nothing and always return - success. These do not make for a usable backend on their own since the - platform implementation would fail to create a window, but are useful for - other backends to reuse since not all need non-trivial implementations of - every backend function. - - @{ -*/ - -static inline PuglStatus -puglStubConfigure(PuglView* view) -{ - (void)view; - return PUGL_SUCCESS; -} - -static inline PuglStatus -puglStubCreate(PuglView* view) -{ - (void)view; - return PUGL_SUCCESS; -} - -static inline PuglStatus -puglStubDestroy(PuglView* view) -{ - (void)view; - return PUGL_SUCCESS; -} - -static inline PuglStatus -puglStubEnter(PuglView* view, bool drawing) -{ - (void)view; - (void)drawing; - return PUGL_SUCCESS; -} - -static inline PuglStatus -puglStubLeave(PuglView* view, bool drawing) -{ - (void)view; - (void)drawing; - return PUGL_SUCCESS; -} - -static inline PuglStatus -puglStubResize(PuglView* view, int width, int height) -{ - (void)view; - (void)width; - (void)height; - return PUGL_SUCCESS; -} - -static inline void* -puglStubGetContext(PuglView* view) -{ - (void)view; - return NULL; -} - -/** - @} -*/ - -#ifdef __cplusplus -} /* extern "C" */ -#endif +#warning "This header is deprecated, use pugl/pugl_stub.h instead." +#include "pugl/pugl_stub.h" #endif // PUGL_PUGL_STUB_BACKEND_H diff --git a/test/pugl_cairo_test.c b/test/pugl_cairo_test.c index ca4d368..22f54a4 100644 --- a/test/pugl_cairo_test.c +++ b/test/pugl_cairo_test.c @@ -21,7 +21,7 @@ #include "test_utils.h" #include "pugl/pugl.h" -#include "pugl/pugl_cairo_backend.h" +#include "pugl/pugl_cairo.h" #include diff --git a/test/pugl_gl3_test.c b/test/pugl_gl3_test.c index 80a8912..8dea5a1 100644 --- a/test/pugl_gl3_test.c +++ b/test/pugl_gl3_test.c @@ -43,7 +43,7 @@ #include "pugl/gl.h" #include "pugl/pugl.h" -#include "pugl/pugl_gl_backend.h" +#include "pugl/pugl_gl.h" #include #include diff --git a/test/pugl_print_events.c b/test/pugl_print_events.c index 1a0e079..da486aa 100644 --- a/test/pugl_print_events.c +++ b/test/pugl_print_events.c @@ -21,7 +21,7 @@ #include "test_utils.h" #include "pugl/pugl.h" -#include "pugl/pugl_stub_backend.h" +#include "pugl/pugl_stub.h" #include #include diff --git a/test/pugl_test.c b/test/pugl_test.c index 99720d2..e158da2 100644 --- a/test/pugl_test.c +++ b/test/pugl_test.c @@ -24,7 +24,7 @@ #include "pugl/gl.h" #include "pugl/pugl.h" -#include "pugl/pugl_gl_backend.h" +#include "pugl/pugl_gl.h" #include #include -- cgit v1.2.1