Skip to content
Search

CEF Python

lastmod 2024-12-26created 2024-09-133 edits

Python bindings for the Chromium Embedded Framework (CEF)

Off-screen rendering

Off-screen rendering, OSR for short, also called windowless rendering, is a method of rendering a page into a memory buffer without creating an actual visible window.

This rendering method has its advantages and its disadvantages.

Its main use is that web page rendering can be integrated into apps that have their own rendering system, and web browser content can be drawn only when a pixel buffer to draw into is provided.

CEF Python provides several examples of integrating CEF off-screen rendering with frameworks such as Kivy, Panda3D, and Pygame/PyOpenGl.

"""
Example of using CEF browser in off-screen rendering mode
(windowless) to create a screenshot of a web page. This
example doesn't depend on any third party GUI framework.
This example is discussed in Tutorial in the Off-screen
rendering section.

Before running this script you have to install Pillow image
library (PIL module):

    pip install Pillow

With optionl arguments to this script you can resize viewport
so that screenshot includes whole page with height like 5000px
which would be an equivalent of scrolling down multiple pages.
By default when no arguments are provided will load cefpython
project page on Github with 5000px height.

Usage:
    python screenshot.py
    python screenshot.py https://github.com/cztomczak/cefpython 1024 5000
    python screenshot.py https://www.google.com/ncr 1024 768

Tested configurations:
- CEF Python v57.0+
- Pillow 2.3.0 / 4.1.0

NOTE: There are limits in Chromium on viewport size. For some
      websites with huge viewport size it won't work. In such
      case it is required to reduce viewport size to an usual
      size of a window and perform scrolling programmatically
      using javascript while making a screenshot for each of
      the scrolled region. Then at the end combine all the
      screenshots into one. To force a paint event in OSR
      mode call cef.Invalidate().
"""

from cefpython3 import cefpython as cef
import os
import platform
import subprocess
import sys

try:
    from PIL import Image, __version__ as PILLOW_VERSION
except ImportError:
    print("[screenshot.py] Error: PIL module not available. To install"
          " type: pip install Pillow")
    sys.exit(1)


# Config
URL = "https://github.com/cztomczak/cefpython"
VIEWPORT_SIZE = (1024, 5000)
SCREENSHOT_PATH = os.path.join(os.path.abspath(os.path.dirname(__file__)),
                               "screenshot.png")


def main():
    check_versions()
    sys.excepthook = cef.ExceptHook  # To shutdown all CEF processes on error
    if os.path.exists(SCREENSHOT_PATH):
        print("[screenshot.py] Remove old screenshot")
        os.remove(SCREENSHOT_PATH)
    command_line_arguments()
    # Off-screen-rendering requires setting "windowless_rendering_enabled"
    # option.
    settings = {
        "windowless_rendering_enabled": True,
    }
    switches = {
        # GPU acceleration is not supported in OSR mode, so must disable
        # it using these Chromium switches (Issue #240 and #463)
        "disable-gpu": "",
        "disable-gpu-compositing": "",
        # Tweaking OSR performance by setting the same Chromium flags
        # as in upstream cefclient (Issue #240).
        "enable-begin-frame-scheduling": "",
        "disable-surfaces": "",  # This is required for PDF ext to work
    }
    browser_settings = {
        # Tweaking OSR performance (Issue #240)
        "windowless_frame_rate": 30,  # Default frame rate in CEF is 30
    }
    cef.Initialize(settings=settings, switches=switches)
    create_browser(browser_settings)
    cef.MessageLoop()
    cef.Shutdown()
    print("[screenshot.py] Opening screenshot with default application")
    open_with_default_application(SCREENSHOT_PATH)


def check_versions():
    ver = cef.GetVersion()
    print("[screenshot.py] CEF Python {ver}".format(ver=ver["version"]))
    print("[screenshot.py] Chromium {ver}".format(ver=ver["chrome_version"]))
    print("[screenshot.py] CEF {ver}".format(ver=ver["cef_version"]))
    print("[screenshot.py] Python {ver} {arch}".format(
           ver=platform.python_version(),
           arch=platform.architecture()[0]))
    print("[screenshot.py] Pillow {ver}".format(ver=PILLOW_VERSION))
    assert cef.__version__ >= "57.0", "CEF Python v57.0+ required to run this"


def command_line_arguments():
    if len(sys.argv) == 4:
        url = sys.argv[1]
        width = int(sys.argv[2])
        height = int(sys.argv[3])
        if url.startswith("http://") or url.startswith("https://"):
            global URL
            URL = url
        else:
            print("[screenshot.py] Error: Invalid url argument")
            sys.exit(1)
        if width > 0 and height > 0:
            global VIEWPORT_SIZE
            VIEWPORT_SIZE = (width, height)
        else:
            print("[screenshot.py] Error: Invalid width and height")
            sys.exit(1)

    elif len(sys.argv) > 1:
        print("[screenshot.py] Error: Expected arguments: url width height")
        sys.exit(1)


def create_browser(settings):
    # Create browser in off-screen-rendering mode (windowless mode)
    # by calling SetAsOffscreen method. In such mode parent window
    # handle can be NULL (0).
    parent_window_handle = 0
    window_info = cef.WindowInfo()
    window_info.SetAsOffscreen(parent_window_handle)
    print("[screenshot.py] Viewport size: {size}"
          .format(size=str(VIEWPORT_SIZE)))
    print("[screenshot.py] Loading url: {url}"
          .format(url=URL))
    browser = cef.CreateBrowserSync(window_info=window_info,
                                    settings=settings,
                                    url=URL)
    browser.SetClientHandler(LoadHandler())
    browser.SetClientHandler(RenderHandler())
    browser.SendFocusEvent(True)
    # You must call WasResized at least once to let know CEF that
    # viewport size is available and that OnPaint may be called.
    browser.WasResized()


def save_screenshot(browser):
    # Browser object provides GetUserData/SetUserData methods
    # for storing custom data associated with browser. The
    # "OnPaint.buffer_string" data is set in RenderHandler.OnPaint.
    buffer_string = browser.GetUserData("OnPaint.buffer_string")
    if not buffer_string:
        raise Exception("buffer_string is empty, OnPaint never called?")
    image = Image.frombytes("RGBA", VIEWPORT_SIZE, buffer_string,
                            "raw", "RGBA", 0, 1)
    image.save(SCREENSHOT_PATH, "PNG")
    print("[screenshot.py] Saved image: {path}".format(path=SCREENSHOT_PATH))
    # See comments in exit_app() why PostTask must be used
    cef.PostTask(cef.TID_UI, exit_app, browser)


def open_with_default_application(path):
    if sys.platform.startswith("darwin"):
        subprocess.call(("open", path))
    elif os.name == "nt":
        # noinspection PyUnresolvedReferences
        os.startfile(path)
    elif os.name == "posix":
        subprocess.call(("xdg-open", path))


def exit_app(browser):
    # Important note:
    #   Do not close browser nor exit app from OnLoadingStateChange
    #   OnLoadError or OnPaint events. Closing browser during these
    #   events may result in unexpected behavior. Use cef.PostTask
    #   function to call exit_app from these events.
    print("[screenshot.py] Close browser and exit app")
    browser.CloseBrowser()
    cef.QuitMessageLoop()


class LoadHandler(object):
    def OnLoadingStateChange(self, browser, is_loading, **_):
        """Called when the loading state has changed."""
        if not is_loading:
            # Loading is complete
            sys.stdout.write(os.linesep)
            print("[screenshot.py] Web page loading is complete")
            print("[screenshot.py] Will save screenshot in 2 seconds")
            # Give up to 2 seconds for the OnPaint call. Most of the time
            # it is already called, but sometimes it may be called later.
            cef.PostDelayedTask(cef.TID_UI, 2000, save_screenshot, browser)

    def OnLoadError(self, browser, frame, error_code, failed_url, **_):
        """Called when the resource load for a navigation fails
        or is canceled."""
        if not frame.IsMain():
            # We are interested only in loading main url.
            # Ignore any errors during loading of other frames.
            return
        print("[screenshot.py] ERROR: Failed to load url: {url}"
              .format(url=failed_url))
        print("[screenshot.py] Error code: {code}"
              .format(code=error_code))
        # See comments in exit_app() why PostTask must be used
        cef.PostTask(cef.TID_UI, exit_app, browser)


class RenderHandler(object):
    def __init__(self):
        self.OnPaint_called = False

    def GetViewRect(self, rect_out, **_):
        """Called to retrieve the view rectangle which is relative
        to screen coordinates. Return True if the rectangle was
        provided."""
        # rect_out --> [x, y, width, height]
        rect_out.extend([0, 0, VIEWPORT_SIZE[0], VIEWPORT_SIZE[1]])
        return True

    def OnPaint(self, browser, element_type, paint_buffer, **_):
        """Called when an element should be painted."""
        if self.OnPaint_called:
            sys.stdout.write(".")
            sys.stdout.flush()
        else:
            sys.stdout.write("[screenshot.py] OnPaint")
            self.OnPaint_called = True
        if element_type == cef.PET_VIEW:
            # Buffer string is a huge string, so for performance
            # reasons it would be better not to copy this string.
            # I think that Python makes a copy of that string when
            # passing it to SetUserData.
            buffer_string = paint_buffer.GetBytes(mode="rgba",
                                                  origin="top-left")
            # Browser object provides GetUserData/SetUserData methods
            # for storing custom data associated with browser.
            browser.SetUserData("OnPaint.buffer_string", buffer_string)
        else:
            raise Exception("Unsupported element_type in OnPaint")


if __name__ == '__main__':
    main()

How to pass user events to CEF

WARNING

This is an answer from ChatGPT. Needs verification.

The way to handle user events (mouse clicks, keyboard input, etc.) while rendering CefPython with PyOpenGL is to use CEF's SendMouseClickEvent and SendKeyEvent APIs.

Events are detected in the OpenGL context and passed to CEF so that the browser interacts with them.

Below is the basic flow for passing user events from PyOpenGL to CEF:

from cefpython3 import cefpython as cef
from OpenGL.GL import *
from OpenGL.GLUT import *
import sys

# 초기 설정
browser = None
window_width = 800
window_height = 600

def main():
    global browser

    # 초기화
    cef.Initialize()
    glutInit(sys.argv)
    glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGB | GLUT_DEPTH)
    glutInitWindowSize(window_width, window_height)
    glutCreateWindow(b"CEF with PyOpenGL")

    # 브라우저 생성
    browser_settings = {}
    browser = cef.CreateBrowserSync(url="https://www.python.org",
                                    window_title="CEF Python with OpenGL",
                                    window_info=cef.WindowInfo())
    browser.SetClientHandler(LoadHandler())

    # OpenGL 초기화
    glutDisplayFunc(render)
    glutReshapeFunc(on_resize)
    glutMouseFunc(on_mouse_click)
    glutMotionFunc(on_mouse_move)
    glutKeyboardFunc(on_key)
    glutMainLoop()

    # 종료
    cef.Shutdown()

# 렌더링 함수
def render():
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
    if browser:
        browser.SendFocusEvent(True)
        cef.MessageLoopWork()
    glutSwapBuffers()
    glutPostRedisplay()

# 윈도우 리사이즈 처리
def on_resize(width, height):
    global window_width, window_height
    window_width = width
    window_height = height
    glViewport(0, 0, width, height)
    if browser:
        browser.WasResized()

# 마우스 클릭 이벤트 처리
def on_mouse_click(button, state, x, y):
    if browser:
        cef.ButtonType = cef.MOUSEBUTTON_LEFT if button == 0 else cef.MOUSEBUTTON_RIGHT
        mouse_event = {
            "x": x,
            "y": y,
            "modifiers": cef.EVENTFLAG_LEFT_MOUSE_BUTTON if button == 0 else 0
        }
        mouse_type = cef.MOUSEBUTTON_LEFT if button == 0 else cef.MOUSEBUTTON_RIGHT
        browser.SendMouseClickEvent(mouse_event["x"], mouse_event["y"], mouse_type, 
                                    mouseUp=(state == 0), clickCount=1)

# 마우스 이동 이벤트 처리
def on_mouse_move(x, y):
    if browser:
        mouse_event = {"x": x, "y": y, "modifiers": 0}
        browser.SendMouseMoveEvent(mouse_event["x"], mouse_event["y"], mouseLeave=False)

# 키보드 이벤트 처리
def on_key(key, x, y):
    if browser:
        key_event = {
            "type": cef.KEYEVENT_CHAR,
            "windows_key_code": ord(key),
            "native_key_code": ord(key),
            "modifiers": 0,
            "is_system_key": False
        }
        browser.SendKeyEvent(key_event)

# 브라우저 로드 핸들러 (필요시 구현)
class LoadHandler(object):
    def OnLoadingStateChange(self, browser, is_loading, **_):
        if not is_loading:
            print("Page Loaded")

if __name__ == "__main__":
    main()

Overall flow:

Detect mouse/keyboard events in OpenGL
Handle events using GLUT callbacks such as glutMouseFunc and glutKeyboardFunc.
Pass events to CEF
Send events to CEF using SendMouseClickEvent, SendMouseMoveEvent, and SendKeyEvent.

See also

Favorite site

author Zer0 sitemap