.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.GraphicsRenderer:

==========================================================================================================================================
|phoenix_title|  **wx.GraphicsRenderer**
==========================================================================================================================================

A :ref:`wx.GraphicsRenderer`  is the instance corresponding to the rendering engine used.          

There may be multiple instances on a system, if there are different rendering engines present, but there is always only one instance per engine. This instance is pointed back to by all objects created by it (:ref:`wx.GraphicsContext`, :ref:`wx.GraphicsPath`  etc.) and can be retrieved through their :meth:`wx.GraphicsObject.GetRenderer`   method. Therefore you can create an additional instance of a path etc. by calling :meth:`wx.GraphicsObject.GetRenderer`   and then using the appropriate CreateXXX() function of that renderer. 

::

        path = wx.GraphicsPath() # from somewhere
        brush = path.GetRenderer().CreateBrush(wx.BLACK_BRUSH)









|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>GraphicsRenderer</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.GraphicsRenderer_inheritance.png" alt="Inheritance diagram of GraphicsRenderer" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.GraphicsRenderer.html" title="wx.GraphicsRenderer" alt="" coords="5,83,165,112"/> <area shape="rect" id="node2" href="wx.Object.html" title="wx.Object" alt="" coords="42,5,129,35"/> </map> 
   </p>
   </div>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.GraphicsRenderer.CreateBitmap`                                        Creates :ref:`wx.GraphicsBitmap`  from an existing :ref:`wx.Bitmap`.
:meth:`~wx.GraphicsRenderer.CreateBitmapFromImage`                               Creates :ref:`wx.GraphicsBitmap`  from an existing :ref:`wx.Image`.
:meth:`~wx.GraphicsRenderer.CreateBitmapFromNativeBitmap`                        Creates :ref:`wx.GraphicsBitmap`  from a native bitmap handle.
:meth:`~wx.GraphicsRenderer.CreateBrush`                                         Creates a native brush from a :ref:`wx.Brush`.
:meth:`~wx.GraphicsRenderer.CreateContext`                                       Creates a :ref:`wx.GraphicsContext`  from a :ref:`wx.Window`.
:meth:`~wx.GraphicsRenderer.CreateContextFromImage`                              Creates a :ref:`wx.GraphicsContext`  associated with a :ref:`wx.Image`.
:meth:`~wx.GraphicsRenderer.CreateContextFromNativeContext`                      Creates a :ref:`wx.GraphicsContext`  from a native context.
:meth:`~wx.GraphicsRenderer.CreateContextFromNativeWindow`                       Creates a :ref:`wx.GraphicsContext`  from a native window.
:meth:`~wx.GraphicsRenderer.CreateContextFromUnknownDC`                          Creates a :ref:`wx.GraphicsContext`  from a DC of unknown specific type.
:meth:`~wx.GraphicsRenderer.CreateFont`                                          Creates a native graphics font from a :ref:`wx.Font`  and a text colour.
:meth:`~wx.GraphicsRenderer.CreateFontAtDPI`                                     Creates a native graphics font from a :ref:`wx.Font`  and a text colour.
:meth:`~wx.GraphicsRenderer.CreateImageFromBitmap`                               Creates a :ref:`wx.Image`  from a :ref:`wx.GraphicsBitmap`.
:meth:`~wx.GraphicsRenderer.CreateLinearGradientBrush`                           Creates a native brush with a linear gradient.
:meth:`~wx.GraphicsRenderer.CreateMatrix`                                        Creates a native affine transformation matrix from the passed in values.
:meth:`~wx.GraphicsRenderer.CreateMeasuringContext`                              Creates a :ref:`wx.GraphicsContext`  that can be used for measuring texts only.
:meth:`~wx.GraphicsRenderer.CreatePath`                                          Creates a native graphics path which is initially empty.
:meth:`~wx.GraphicsRenderer.CreatePen`                                           Creates a native pen from its description.
:meth:`~wx.GraphicsRenderer.CreateRadialGradientBrush`                           Creates a native brush with a radial gradient.
:meth:`~wx.GraphicsRenderer.CreateSubBitmap`                                     Extracts a sub-bitmap from an existing bitmap.
:meth:`~wx.GraphicsRenderer.GetCairoRenderer`                                    Returns Cairo renderer.
:meth:`~wx.GraphicsRenderer.GetDefaultRenderer`                                  Returns the default renderer on this platform.
:meth:`~wx.GraphicsRenderer.GetDirect2DRenderer`                                 Returns Direct2D renderer (MSW and Python3 only).
:meth:`~wx.GraphicsRenderer.GetGDIPlusRenderer`                                  Returns GDI+ renderer (MSW only).
:meth:`~wx.GraphicsRenderer.GetName`                                             Returns the name of the technology used by the renderer.
:meth:`~wx.GraphicsRenderer.GetType`                                             Returns the name of the GraphicsRenderer class.
:meth:`~wx.GraphicsRenderer.GetVersion`                                          Returns the version major, minor and micro/build of the technology used by the renderer.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.GraphicsRenderer.Name`                                                See :meth:`~wx.GraphicsRenderer.GetName`
:attr:`~wx.GraphicsRenderer.Type`                                                See :meth:`~wx.GraphicsRenderer.GetType`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.GraphicsRenderer(Object)

   A GraphicsRenderer is the instance corresponding to the rendering
   engine used.



   .. method:: CreateBitmap(self, bitmap)

      Creates :ref:`wx.GraphicsBitmap`  from an existing :ref:`wx.Bitmap`.                  

      Returns an invalid NullGraphicsBitmap on failure.                  


      :param `bitmap`: 
      :type `bitmap`: wx.Bitmap




      :rtype: :ref:`wx.GraphicsBitmap`








   .. method:: CreateBitmapFromImage(self, image)

      Creates :ref:`wx.GraphicsBitmap`  from an existing :ref:`wx.Image`.                  

      This method is more efficient than converting :ref:`wx.Image`  to :ref:`wx.Bitmap`  first and then calling :meth:`CreateBitmap`   but otherwise has the same effect. 

      Returns an invalid NullGraphicsBitmap on failure. 

                


      :param `image`: 
      :type `image`: wx.Image




      :rtype: :ref:`wx.GraphicsBitmap`







      .. versionadded:: 2.9.3 
     








   .. method:: CreateBitmapFromNativeBitmap(self, bitmap)

      Creates :ref:`wx.GraphicsBitmap`  from a native bitmap handle.                  

      `bitmap`  meaning is platform-dependent. Currently it's a GDI+  ``Bitmap``   pointer under MSW,   ``CGImage``   pointer under macOS or a   ``cairo_surface_t``   pointer when using Cairo under any platform. 

      Notice that this method takes ownership of `bitmap`, i.e. it will be destroyed when the returned :ref:`wx.GraphicsBitmap`  is.                  


      :param `bitmap`: 




      :rtype: :ref:`wx.GraphicsBitmap`








   .. method:: CreateBrush(self, brush)

      Creates a native brush from a :ref:`wx.Brush`.                  


      :param `brush`: 
      :type `brush`: wx.Brush




      :rtype: :ref:`wx.GraphicsBrush`








   .. method:: CreateContext(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **CreateContext** `(self, window)`
      
      Creates a :ref:`wx.GraphicsContext`  from a :ref:`wx.Window`.                  
      
      
      :param `window`: 
      :type `window`: wx.Window
      
      
      
      
      :rtype: :ref:`wx.GraphicsContext`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **CreateContext** `(self, windowDC)`
      
      Creates a :ref:`wx.GraphicsContext`  from a :ref:`wx.WindowDC`.                  
      
      
      :param `windowDC`: 
      :type `windowDC`: wx.WindowDC
      
      
      
      
      :rtype: :ref:`wx.GraphicsContext`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **CreateContext** `(self, memoryDC)`
      
      Creates a :ref:`wx.GraphicsContext`  from a :ref:`wx.MemoryDC`.                  
      
      
      :param `memoryDC`: 
      :type `memoryDC`: wx.MemoryDC
      
      
      
      
      :rtype: :ref:`wx.GraphicsContext`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **CreateContext** `(self, printerDC)`
      
      Creates a :ref:`wx.GraphicsContext`  from a :ref:`wx.PrinterDC`.                  
      
                      
      
      
      :param `printerDC`: 
      :type `printerDC`: wx.PrinterDC
      
      
      
      
      :rtype: :ref:`wx.GraphicsContext`
      
      
      
      
      
      
      
      .. note:: 
      
         Not implemented for Direct2D renderer (on MSW).   
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: CreateContextFromImage(self, image)

      Creates a :ref:`wx.GraphicsContext`  associated with a :ref:`wx.Image`.                  

      This function is used by `Context.CreateFromImage()` and is not normally called directly. 

                


      :param `image`: 
      :type `image`: wx.Image




      :rtype: :ref:`wx.GraphicsContext`







      .. versionadded:: 2.9.3 
     








   .. method:: CreateContextFromNativeContext(self, context)

      Creates a :ref:`wx.GraphicsContext`  from a native context.                  

      This native context must be a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus, an ID2D1RenderTarget pointer for Direct2D, a cairo_t pointer or ``HDC`` for Cairo on MSW, or a cairo_t pointer for Cairo on any other platform.                  


      :param `context`: 




      :rtype: :ref:`wx.GraphicsContext`








   .. method:: CreateContextFromNativeWindow(self, window)

      Creates a :ref:`wx.GraphicsContext`  from a native window.                  


      :param `window`: 




      :rtype: :ref:`wx.GraphicsContext`








   .. method:: CreateContextFromUnknownDC(self, dc)

      Creates a :ref:`wx.GraphicsContext`  from a DC of unknown specific type.                  

      Creates a :ref:`wx.GraphicsContext`  if `dc`  is a supported type (i.e. has a corresponding :meth:`CreateContext`   method, e.g. :ref:`wx.WindowDC`  or :ref:`wx.MemoryDC`). Returns ``None`` if the DC is unsupported. 

      This method is only useful as a helper in generic code that operates with :ref:`wx.DC`  and doesn't known its exact type. Use the appropriate :meth:`CreateContext`   overload instead if you know that the DC is e.g. :ref:`wx.WindowDC`. 

                


      :param `dc`: 
      :type `dc`: wx.DC




      :rtype: :ref:`wx.GraphicsContext`







      .. versionadded:: 4.1/wxWidgets-3.1.3  
     







      .. seealso:: :meth:`wx.GraphicsContext.CreateFromUnknownDC`   








   .. method:: CreateFont(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **CreateFont** `(self, font, col=BLACK)`
      
      Creates a native graphics font from a :ref:`wx.Font`  and a text colour.                  
      
      
      :param `font`: 
      :type `font`: wx.Font
      :param `col`: 
      :type `col`: wx.Colour
      
      
      
      
      :rtype: :ref:`wx.GraphicsFont`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **CreateFont** `(self, sizeInPixels, facename, flags=FONTFLAG_DEFAULT, col=BLACK)`
      
      Creates a graphics font with the given characteristics.                  
      
      If possible, the :meth:`CreateFont`   overload taking :ref:`wx.Font`  should be used instead. The main advantage of this overload is that it can be used without X server connection under Unix when using Cairo. 
      
      
      
      
      :param `sizeInPixels`: Height of the font in user space units, i.e. normally pixels. Notice that this is different from the overload taking :ref:`wx.Font`  as :ref:`wx.Font`  size is specified in points.   
      :type `sizeInPixels`: float
      :param `facename`: The name of the font. The same font name might not be available under all platforms so the font name can also be empty to use the default platform font.   
      :type `facename`: string
      :param `flags`: Combination of FontFlag enum elements. Currently only  ``FONTFLAG_ITALIC``   and   ``FONTFLAG_BOLD``   are supported. By default the normal font version is used.    
      :type `flags`: int
      :param `col`: The font colour, black by default.  
      :type `col`: wx.Colour
      
      
      
      
      
      
      
      
      
      
      
      
      :rtype: :ref:`wx.GraphicsFont`
      
      
      
                        
      
      
      
      .. versionadded:: 2.9.3 
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: CreateFontAtDPI(self, font, dpi, col=BLACK)

      Creates a native graphics font from a :ref:`wx.Font`  and a text colour.                  

      The specified ``DPI`` is used to convert the (fractional) :ref:`wx.Font`  point-size to a fractional pixel-size. 

                


      :param `font`: 
      :type `font`: wx.Font
      :param `dpi`: 
      :type `dpi`: wx.RealPoint
      :param `col`: 
      :type `col`: wx.Colour




      :rtype: :ref:`wx.GraphicsFont`







      .. versionadded:: 4.1/wxWidgets-3.1.3  
     








   .. method:: CreateImageFromBitmap(self, bmp)

      Creates a :ref:`wx.Image`  from a :ref:`wx.GraphicsBitmap`.                  

      This method is used by the more convenient :meth:`wx.GraphicsBitmap.ConvertToImage` .                  


      :param `bmp`: 
      :type `bmp`: wx.GraphicsBitmap




      :rtype: :ref:`wx.Image`








   .. method:: CreateLinearGradientBrush(self, x1, y1, x2, y2, stops, matrix=NullGraphicsMatrix)

      Creates a native brush with a linear gradient.                  

      Stops support is new since wxWidgets 2.9.1, previously only the start and end colours could be specified. 

      The ability to apply a transformation matrix to the gradient was added in 3.1.3                  


      :param `x1`: 
      :type `x1`: wx.Double
      :param `y1`: 
      :type `y1`: wx.Double
      :param `x2`: 
      :type `x2`: wx.Double
      :param `y2`: 
      :type `y2`: wx.Double
      :param `stops`: 
      :type `stops`: wx.GraphicsGradientStops
      :param `matrix`: 
      :type `matrix`: wx.GraphicsMatrix




      :rtype: :ref:`wx.GraphicsBrush`








   .. method:: CreateMatrix(self, a=1.0, b=0.0, c=0.0, d=1.0, tx=0.0, ty=0.0)

      Creates a native affine transformation matrix from the passed in values.                  

      The defaults result in an identity matrix.                  


      :param `a`: 
      :type `a`: wx.Double
      :param `b`: 
      :type `b`: wx.Double
      :param `c`: 
      :type `c`: wx.Double
      :param `d`: 
      :type `d`: wx.Double
      :param `tx`: 
      :type `tx`: wx.Double
      :param `ty`: 
      :type `ty`: wx.Double




      :rtype: :ref:`wx.GraphicsMatrix`








   .. method:: CreateMeasuringContext(self)

      Creates a :ref:`wx.GraphicsContext`  that can be used for measuring texts only.                  

      No drawing commands are allowed.                  

      :rtype: :ref:`wx.GraphicsContext`








   .. method:: CreatePath(self)

      Creates a native graphics path which is initially empty.                  

      :rtype: :ref:`wx.GraphicsPath`








   .. method:: CreatePen(self, info)

      Creates a native pen from its description.                  

                


      :param `info`: 
      :type `info`: wx.GraphicsPenInfo




      :rtype: :ref:`wx.GraphicsPen`







      .. versionadded:: 4.1/wxWidgets-3.1.1  
     








   .. method:: CreateRadialGradientBrush(self, startX, startY, endX, endY, radius, stops, matrix=NullGraphicsMatrix)

      Creates a native brush with a radial gradient.                  

      Stops support is new since wxWidgets 2.9.1, previously only the start and end colours could be specified. 

      The ability to apply a transformation matrix to the gradient was added in 3.1.3                  


      :param `startX`: 
      :type `startX`: wx.Double
      :param `startY`: 
      :type `startY`: wx.Double
      :param `endX`: 
      :type `endX`: wx.Double
      :param `endY`: 
      :type `endY`: wx.Double
      :param `radius`: 
      :type `radius`: wx.Double
      :param `stops`: 
      :type `stops`: wx.GraphicsGradientStops
      :param `matrix`: 
      :type `matrix`: wx.GraphicsMatrix




      :rtype: :ref:`wx.GraphicsBrush`








   .. method:: CreateSubBitmap(self, bitmap, x, y, w, h)

      Extracts a sub-bitmap from an existing bitmap.                  


      :param `bitmap`: 
      :type `bitmap`: wx.GraphicsBitmap
      :param `x`: 
      :type `x`: wx.Double
      :param `y`: 
      :type `y`: wx.Double
      :param `w`: 
      :type `w`: wx.Double
      :param `h`: 
      :type `h`: wx.Double




      :rtype: :ref:`wx.GraphicsBitmap`








   .. staticmethod:: GetCairoRenderer()

      Returns Cairo renderer.                  

      :rtype: :ref:`wx.GraphicsRenderer`








   .. staticmethod:: GetDefaultRenderer()

      Returns the default renderer on this platform.                  

      On macOS this is the Core Graphics (a.k.a. Quartz ``2D``) renderer, on MSW the GDIPlus renderer, and on GTK we currently default to the Cairo renderer.                  

      :rtype: :ref:`wx.GraphicsRenderer`








   .. staticmethod:: GetDirect2DRenderer()

      Returns Direct2D renderer (MSW and Python3 only). 

      :rtype: :ref:`wx.GraphicsRenderer`








   .. staticmethod:: GetGDIPlusRenderer()

      Returns GDI+ renderer (MSW only). 

      :rtype: :ref:`wx.GraphicsRenderer`








   .. method:: GetName(self)

      Returns the name of the technology used by the renderer.                  

      Currently this function returns "gdiplus" for Windows GDI+ implementation, "direct2d" for Windows Direct2D implementation, "cairo" for Cairo implementation and "cg" for macOS CoreGraphics implementation. 

                

      :rtype: `string`







      .. versionadded:: 4.1/wxWidgets-3.1.0  
     







      .. note:: 

         The string returned by this method is not user-readable and is expected to be used internally by the program only.  








   .. method:: GetType(self)

      Returns the name of the GraphicsRenderer class.



   .. method:: GetVersion(self, major, minor=None, micro=None)

      Returns the version major, minor and micro/build of the technology used by the renderer.                  

      Currently this function returns the OS major and minor versions in the parameters with the matching names and sets `micro`  to 0 for the GDI+ and CoreGraphics engines which are considered to be parts of their respective OS. 

      For Cairo, this is the major,minor,micro version of the Cairo library which is returned.                  


      :param `major`: 
      :type `major`: int
      :param `minor`: 
      :type `minor`: int
      :param `micro`: 
      :type `micro`: int







   .. attribute:: Name

      See :meth:`~wx.GraphicsRenderer.GetName`


   .. attribute:: Type

      See :meth:`~wx.GraphicsRenderer.GetType`