[haiku-commits] haiku: hrev47709 - docs/develop/opengl

  • From: kallisti5@xxxxxxxxxxx
  • To: haiku-commits@xxxxxxxxxxxxx
  • Date: Tue, 19 Aug 2014 16:39:36 +0200 (CEST)

hrev47709 adds 2 changesets to branch 'master'
old head: f66aa8595c256a17177056f1596901be6b2f7b03
new head: ea28139d8429cbad6103a5fb95beb2d8540cc7b3
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=ea28139+%5Ef66aa85

----------------------------------------------------------------------------

4662c8c: docs: opengl. Add some great documentation provided by Roudolf.
  
  * Posted to the haiku-appserver ML, circa 2005.
  * Covers a lot of intended uses of Be's accelerant API's in
    depth and compares them to moden cards

ea28139: docs: Update opengl readme info

                          [ Alexander von Gluck IV <kallisti5@xxxxxxxxxxx> ]

----------------------------------------------------------------------------

2 files changed, 160 insertions(+), 78 deletions(-)
docs/develop/opengl/accelerant-interfaces | 136 ++++++++++++++++++++++++++
docs/develop/opengl/readme                | 102 +++++--------------

############################################################################

Commit:      4662c8c0a9668798b2eedcd2041108ccd6630ac9
URL:         http://cgit.haiku-os.org/haiku/commit/?id=4662c8c
Author:      Alexander von Gluck IV <kallisti5@xxxxxxxxxxx>
Date:        Tue Aug 19 14:28:53 2014 UTC

docs: opengl. Add some great documentation provided by Roudolf.

* Posted to the haiku-appserver ML, circa 2005.
* Covers a lot of intended uses of Be's accelerant API's in
  depth and compares them to moden cards

----------------------------------------------------------------------------

diff --git a/docs/develop/opengl/accelerant-interfaces 
b/docs/develop/opengl/accelerant-interfaces
new file mode 100644
index 0000000..1138b86
--- /dev/null
+++ b/docs/develop/opengl/accelerant-interfaces
@@ -0,0 +1,136 @@
+Posted by Rudolf Nov 22, 2005 to the haiku-appsever ML:
+//www.freelists.org/post/haiku-appserver/new-drawing-bug-Rudolf-some-stuff-for-you,10
+
+More good info @ //www.freelists.org/archive/haiku-appserver
+
+        Be Docs (file: R4_Graphics_Driver_Docs):
+        
+        Engine Synchronization
+
+        B_ACCELERANT_ENGINE_COUNT  -  No feature specific data required.
+        Return the number of acceleration engines that the device may operate 
in parallel.
+        It's not required for all engines to be equally capable (i.e. support 
the same
+        acceleration features).
+
+        B_ACQUIRE_ENGINE  -  No feature specific data required.
+        Request exclusive ownership of an acceleration engine with the 
capabilities mask specified.
+        The caller is willing to wait up to max_wait micro(milli?)-seconds. If 
the request can't be
+        fullfilled before that time expires, the accelerant should return 
B_WOULD_BLOCK immediatly.
+        If non-zero, sync_token points to a synchronization token retrieved 
from either
+        release_engine() or get_sync_token() to which the engine should be 
synchronized before
+        engine acquisition succeeds.  See B_SYNC_TO_TOKEN for more details.  
The engine_token for
+        the successfully acquired engine is returned in engine_token **et.
+
+        B_RELEASE_ENGINE  -  No feature specific data required.
+        Relinquish exclusive ownership of the engine specified by engine_token 
et.  If
+        sync_token *st is non-zero, return a sync_token which can be utilized 
to ensure that the
+        specified engine has completed all acceleration operations issued up 
this point in time.
+
+        B_WAIT_ENGINE_IDLE  -  No feature specific data required.
+        Wait for the graphics device to be completely idle (i.e. no current 
running or pending
+        acceleration primitives, DMA transfers, etc.).
+
+        B_GET_SYNC_TOKEN  -  No feature specific data required.
+        Return a synchronization token for the specified engine.  sync_token 
*st must point at
+        a sync_token which will be updated with the information required to 
ensure that a call to
+        sync_to_token() will be able to ensure that the specified engine has 
completed all of the
+        acceleration primitives, DMA transfers, etc. that have been issued up 
to this point in time.
+
+        B_SYNC_TO_TOKEN  -  No feature specific data required.
+        Ensure that the engine specified in sync_token *st has completed the 
acceleration
+        primitives, DMA transfers, etc., issued up to the point in time 
specified in the sync_token.
+
+
+        Rudolf's notes.        
+        info on engine_token:
+
+        uint32 ACCELERANT_ENGINE_COUNT(void)
+        exists because in theory a single card can have multiple independant 
acceleration engines.
+        For instance one that can do 2D, and one that can do 3D (or 
combinations). See
+        'engine capabilities' flags in Accelerant.h.
+        (note: never seen multiple engines per card     yet though. Was this 
meant for some very old
+        hardware with seperate 2D and 3D 'blocks'? Although I guess it's 
thinkable that multiple
+        equally capable engines would exist as well..)
+
+        In order to distinquish between multiple engines all acceleration 
commands are given along
+        with an engine_token *et, aquired when
+        status_t ACQUIRE_ENGINE(uint32 capabilities, uint32 max_wait, 
sync_token *st, engine_token **et)
+        was called.
+        status_t SYNC_TO_TOKEN(sync_token *st)
+        is an exeption: here the engine is ID'd by member: (defined in 
Accelerant.h)
+        uint32  engine_id.
+        void WAIT_ENGINE_IDLE(void)
+        is an exeption also because this function returns only when *ALL* 
engines are completely
+        idle. Hence no need for distinction.
+        
+        Furthermore the absense of the use of engine_token in both 
SYNC_TO_TOKEN and WAIT_ENGINE_IDLE
+        would seem to indicate these hooks may be used *without having 
acquired the engine*. (?).
+
+
+        info on sync_token:
+
+--      How does the acceleration cmd interface work? There's a circular 
buffer that stores cmd's.
+        There's a hardware pointer that points 'at' the command currently 
being executed (think
+        of stacks: some architectures point to the first 'free' location, some 
to the 'last used'
+        location.)
+        There's also a second pointer which points at the first free location, 
i.e. where new cmd's
+        will be stored pending execution. This second pointer is a software 
maintained pointer (in
+        the driver).
+
+--      What's a sync_token? A Sync_token in nothing more than a extra pointer 
(one per token). This
+        pointer points at the first free location in the cmd buffer at that 
point in time the 
+        sync_token was 'filled'. In theory it doesn't change during the (rest 
of the) life-time of
+        the token, although the driver-implementation could (?) do that anyway 
for some internal
+        reason.
+        Driver users (i.e. app_server) are responsible for reserving memory 
for a sync_token. They
+        pass a pointer to it to the driver (if they want to use it). The 
driver in turns fills it
+        with the needed info. Driver users may never modify the content of the 
sync_token(s).
+        
+--      When would a user be interested in a sync_token? If multiple 
independant (so non-overlapping)
+        'regions' require multiple updates each alternatingly done by software 
and acceleration engine,
+        it might be interesting to use sync_tokens (for instance).
+        It would be possible to issue all engine commands concerning area #1, 
ask for a sync token,
+        issue all engine commands concerning area #2, and then do this:
+        - SYNC_TO_TOKEN (so waiting until all engine commands concerning area 
#1 are done);
+        - Draw in area #1 using software (while the acc engine is in the 
process of updating area #2:
+         (so some 'parallel processing' is done here).
+
+        If no sync token would be used, instead of syncing to token, 
wait_engine_idle would be used.
+        This of course would mean that no 'parallel processing' could be 
done...
+        Worse yet: if some seperate user is also using the engine (between 
RELEASE and AQUIRE engine
+        done by 'user #1' (i.e. app_server), the acc engine might *never* 
become fully idle.
+        A nice example here would be 3D acceleration: as long as no 
non-accelerated drawing has to be
+        done there, there's no reason the engine would need to be idle at all 
for this (apart from
+        processing 'user-input' like joystick controls).
+        You see: an acceleration engine automatically serializes it's cmd 
processing so update errors
+        because of out-of-order execution wouldn't happen.
+        
+--      Why didn't I implement sync_token stuff in the matrox, nvidia and 
neomagic drivers?
+        Lack of 'known specs' yet. You see, even if the pointers in the cmd 
buffer are known: that's 
+        not enough yet:
+        - The fact that an command is fetched from the buffer does *not* mean 
it's
+        execution is completely done.
+        - The implementation via just a pointer is not enough: if you wait too 
long, the current
+        free pointer might have cycled around the buffer. This means a simple 
compare to that
+        pointer is not conclusive. Much better would be actually inserting 
'dummy commands' inside
+        the command buffer at the place a sync_token is generated. This dummy 
commands would be 
+        executed just once, when we reached our goal. If the dummy command 
clears a variable 
+        especially setup for the sync_token in question: we would have a 
conclusive result without
+        even the use of an actual pointer in the sync_token. AND: updating the 
tokens would have no
+        software overhead, as the acc engine would do it. (via 'pointers only' 
some invalidation
+        code has to be executed once the hardware pointer cycles around).
+
+        NOTE PLEASE:
+        This information is based upon my understanding of hardware inner 
workings. As this 
+        understanding grows and is corrected over time, I might contradict 
myself later on if
+        asked again. :-)         
+
+
+//actual hooks:
+        uint32 ACCELERANT_ENGINE_COUNT(void);
+        status_t ACQUIRE_ENGINE(uint32 capabilities, uint32 max_wait, 
+sync_token *st, engine_token **et);
+        status_t RELEASE_ENGINE(engine_token *et, sync_token *st);
+        status_t GET_SYNC_TOKEN(engine_token *et, sync_token *st);
+        status_t SYNC_TO_TOKEN(sync_token *st);
+        void WAIT_ENGINE_IDLE(void);

############################################################################

Revision:    hrev47709
Commit:      ea28139d8429cbad6103a5fb95beb2d8540cc7b3
URL:         http://cgit.haiku-os.org/haiku/commit/?id=ea28139
Author:      Alexander von Gluck IV <kallisti5@xxxxxxxxxxx>
Date:        Tue Aug 19 14:34:33 2014 UTC

docs: Update opengl readme info

----------------------------------------------------------------------------

diff --git a/docs/develop/opengl/readme b/docs/develop/opengl/readme
index 96dd321..87b00d6 100644
--- a/docs/develop/opengl/readme
+++ b/docs/develop/opengl/readme
@@ -12,23 +12,14 @@ In the traditional BeOS sense, the OpenGL Add-ons are the
 vendor provided OpenGL drivers. This actually doesn't
 mesh well with the current open source OpenGL stack.
 
-Our "OpenGL Add-ons" are really wrappers around Mesa
-and Gallium code.  We gain greater OS control of OpenGL
-rendering with the drawback of increased work overall.
-The OpenGL Add-ons call private Mesa functions, thus
-we get no compatibility saftey net between Mesa versions.
+Our "OpenGL Add-ons" are really self contained Mesa and
+Gallium renderers. On the old Mesa side of the house,
+swrast is a bunch of wrapper code. On the Gallium side,
+swpipe is a Gallium target.
 
-Our Gallium connecting Add-ons could actually fit into
-the upstream Mesa / Gallium project, however this would
-cause complications in the build process (linking in
-OpenGL and all of it's libraries into a small number of
-shared libraries is not really what the Mesa project
-designs it's stack for. Several symbol collisions exist
-when trying to link libmesa and libgallium together for
-example)
-
-Mesa drivers are the classical Mesa software rasterizers
-Gallium drivers are the new-school software drivers.
+Mesa drivers are the classical Mesa software rasterizers,
+Gallium drivers are the new-school software and hardware
+drivers.
 
 
 **********
@@ -36,14 +27,14 @@ Mesa versions
 
 The Haiku project uses two different versions of Mesa.
 
- * Mesa 7.8.2 for gcc2 OpenGL Add-ons
- * Mesa 9.0.1+ for gcc4 OpenGL Add-ons.
+ * Mesa 7.9.2 for gcc2 OpenGL Add-ons
+ * Mesa 10.2.0+ for gcc4 OpenGL Add-ons.
 
 The reasoning behind this is that any version of Mesa
-above 7.8.2 will require a *massive* porting effort to
+above 7.9.2 will require a *massive* porting effort to
 make it compile under gcc2.  Given this fact, it makes
 sense to bump the gcc2 version of Mesa as far as it will
-go and set it there statically.  Think of Mesa 7.8.2
+go and set it there statically.  Think of Mesa 7.9.2
 as the "stable" version Haiku R1 will use :)
 
 Hardware 3D rendering and llvm-based software rendering
@@ -53,68 +44,23 @@ However!  If you're running a gcc2 hybrid version of
 Haiku, llvm or hardware based rendering should be possible
 on gcc4 applications.
 
-It is *essential* to upgrade our build Mesa packages
-with the latest release Mesa versions.  If we fall too
-far behind the update gets extremely tricky as functions
-inside Mesa and Gallium change at a fast pace.
-
-
-**********
-gcc2 OpenGL kit
-
-The following process occurs in order to generate the
-gcc2  (Mesa 7.8.2) OpenGL kit:
-
-* Some kind soul compiles a Mesa optional package on a
-  gcc2 Haiku system with the bep on haikuports.  This
-  gets uploaded to Haiku-files and the package name
-  / version gets updated as in the BuildFeatures jam
-  build script.
-
-  - The bep generally applies a few minimal patches to
-    Mesa 7.8.2 and compiles it. Then it rounds up all of
-    the headers and static libraries and throws them into
-    a .zip for the build
+It's essential someone from the Haiku project keeps up
+with the upstream Mesa changes pushing build fixes to
+upstream Mesa to keep Haiku relevant.
 
-* Someone starts a gcc2 Haiku build.  The build process pulls
-  down the Mesa optional package above and links the needed
-  parts into libGL and the swrast_legacy OpenGL add-on
 
 
 **********
-gcc4 OpenGL kit
-
-The following process occurs in order to generate the
-gcc4  (Mesa 9.0.1+) OpenGL kit:
-
-* Some kind soul compiles a Mesa optional package on a
-  gcc4 Haiku system with the bep on haikuports.  This
-  gets uploaded to Haiku-files and the package name
-  / version gets updated as in the BuildFeatures jam
-  build script.
-
-  - The kind soul also needs to install the LLVM Optional
-    build package on his build machine *before* compiling
-    the Mesa bep. (unless he or she doesn't want llvmpipe
-    rendering)
-
-  - The bep for Mesa 9.0.1+ doesn't apply too many patches as
-    Haiku build fixes are accepted upstream.
-
-  - The bep rounds up all of the headers and static
-    libraries and throws them into a .zip for the build
-
-* Someone starts a gcc4 Haiku build.  The build process pulls
-  down the Mesa optional package above and links the needed
-  parts into libGL and OpenGL add-ons.
+The packages
 
-  - If the user didn't link in LLVM, he can disable the LLVM
-    dependencies in the OpenGL kit Jamfile. swpipe will
-    automagically fall back to softpipe rendering
+Haiku has several packages for Mesa:
 
-  - The build system will download the LLVM optional package
-    and link it into any OpenGL add-ons that need it.
+mesa-x.x.x-x-x86.hpkg        Core Mesa package, provides libGL
+mesa_devel-x.x.x-x-x86.hpkg  Provides development headers and "OpenGL kit"
+mesa_swrast-x.x.x-x-x86.hpkg Mesa "Software Rasterization" renderer
+mesa_swpipe-x.x.x-x-x86.hpkg Gallium "Software pipe" LLVM enhanced renderer
 
-    !! The LLVM optional package needs to match the LLVM
-       binaries on the machine which compiled Mesa
-    !!
+Future :3
+mesa_radeonhd-x.x.x-x-x86.hpkg Gallium "Radeon HD" hardware renderer
+mesa_intel-x.x.x-x-x86.hpkg Gallium "Intel" hardware renderer
+mesa_nvidia-x.x.x-x-x86.hpkg Gallium "nVidia" hardware renderer (unlikely)


Other related posts:

  • » [haiku-commits] haiku: hrev47709 - docs/develop/opengl - kallisti5