From 5c02f37c8d1dd74f3b72f1fb0b2a77f4d1dc2da9 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Mon, 9 Mar 2020 21:50:03 +0100
Subject: Deprecate puglEnterContext() and puglLeaveContext()

These are prone to abuse, and have caused confusion with people who try to use
them like in other libraries that support explicit drawing in the main loop.
The drawing parameter was also wrong, and these were already just compatibility
veneers since the internal context API needs to be more expressive.

So, now that PUGL_CREATE and PUGL_DESTROY exist, they can be deprecated to
force clients to draw only at the correct time.
---
 pugl/detail/implementation.c |  4 +++
 pugl/pugl.h                  | 62 +++++++++++++++++++++++---------------------
 2 files changed, 37 insertions(+), 29 deletions(-)

diff --git a/pugl/detail/implementation.c b/pugl/detail/implementation.c
index 8deb50a..6433faa 100644
--- a/pugl/detail/implementation.c
+++ b/pugl/detail/implementation.c
@@ -243,6 +243,8 @@ puglGetContext(PuglView* view)
 	return view->backend->getContext(view);
 }
 
+#ifndef PUGL_DISABLE_DEPRECATED
+
 PuglStatus
 puglEnterContext(PuglView* view, bool drawing)
 {
@@ -265,6 +267,8 @@ puglLeaveContext(PuglView* view, bool drawing)
 	return PUGL_SUCCESS;
 }
 
+#endif
+
 PuglStatus
 puglSetEventFunc(PuglView* view, PuglEventFunc eventFunc)
 {
diff --git a/pugl/pugl.h b/pugl/pugl.h
index 53327c8..718e76a 100644
--- a/pugl/pugl.h
+++ b/pugl/pugl.h
@@ -888,35 +888,6 @@ puglGetNativeWindow(PuglView* view);
 PUGL_API void*
 puglGetContext(PuglView* view);
 
-/**
-   Enter the graphics context.
-
-   Note that, unlike some similar libraries, Pugl automatically enters and
-   leaves the graphics context when required and application should not
-   normally do this.  Drawing in Pugl is only allowed during the processing of
-   an expose event.
-
-   However, this can be used to enter the graphics context elsewhere, for
-   example to call any GL functions during setup.
-
-   @param view The view being entered.
-   @param drawing If true, prepare for drawing.
-*/
-PUGL_API PuglStatus
-puglEnterContext(PuglView* view, bool drawing);
-
-/**
-   Leave the graphics context.
-
-   This must be called after puglEnterContext() with a matching `drawing`
-   parameter.
-
-   @param view The view being left.
-   @param drawing If true, finish drawing, for example by swapping buffers.
-*/
-PUGL_API PuglStatus
-puglLeaveContext(PuglView* view, bool drawing);
-
 /**
    Request a redisplay for the entire view.
 
@@ -1226,6 +1197,39 @@ puglWaitForEvent(PuglView* view);
 PUGL_API PUGL_DEPRECATED_BY("puglDispatchEvents") PuglStatus
 puglProcessEvents(PuglView* view);
 
+/**
+   Enter the graphics context.
+
+   Note that, unlike some similar libraries, Pugl automatically enters and
+   leaves the graphics context when required and application should not
+   normally do this.  Drawing in Pugl is only allowed during the processing of
+   an expose event.
+
+   However, this can be used to enter the graphics context elsewhere, for
+   example to call any GL functions during setup.
+
+   @param view The view being entered.
+   @param drawing If true, prepare for drawing.
+
+   @deprecated Set up graphics when a #PUGL_CREATE event is received.
+*/
+PUGL_API PUGL_DEPRECATED_BY("PUGL_CREATE") PuglStatus
+puglEnterContext(PuglView* view, bool drawing);
+
+/**
+   Leave the graphics context.
+
+   This must be called after puglEnterContext() with a matching `drawing`
+   parameter.
+
+   @param view The view being left.
+   @param drawing If true, finish drawing, for example by swapping buffers.
+
+   @deprecated Shut down graphics when a #PUGL_DESTROY event is received.
+*/
+PUGL_API PUGL_DEPRECATED_BY("PUGL_DESTROY") PuglStatus
+puglLeaveContext(PuglView* view, bool drawing);
+
 #endif  /* PUGL_DISABLE_DEPRECATED */
 
 /**
-- 
cgit v1.2.1