tutorials/05-cube/CubeTutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Draw a Cube with PySide2 OpenGL"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Welcome to PySide2 OpenGL cube tutorial. \n",
    "\n",
    "Why draw a cube ? So far we had seen only 2d rendering. \n",
    "A cube introduces us to 3d rendering in OpenGL. \n",
    "With respect to 2d rendering it introduces several additional configurations that need to be taken into account which are tied to the very nature of 3d objects. These are:\n",
    "\n",
    "- 3d objects are contained in a 3d world.\n",
    "- 3d objects are observed from somewhere inside the world.\n",
    "- Observation process transforms the 3d object to a 2d object.\n",
    "\n",
    "Now these three facts obliges to use three additional objects in shaders to render a 3d object:\n",
    "\n",
    "- **model** matrix 4x4: determines the position of the object in a 3d world\n",
    "- **view** matrix 4x4: transforms the coordinates of objects in a 3d world with respect to the camera/viewer position\n",
    "- **projection** matrix 4x4: determines how object(s) would appear with respect to the position and the direction of the viewer.\n",
    "\n",
    "It should be more or less clear that 3d rendering needs a little more consideration and effort. \n",
    "\n",
    "Let's see the final form of the application."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "CompletedProcess(args=['python', 'app.py'], returncode=0)"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import subprocess\n",
    "\n",
    "subprocess.run([\"python\", \"app.py\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All right! As usual, I skip the window code and concentrate on the GL widget instead.\n",
    "\n",
    "Let's see the constructor of our widget."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class CubeGL(QOpenGLWidget):\n",
    "    \"Cube gl widget\"\n",
    "\n",
    "    def __init__(self, parent=None):\n",
    "        QOpenGLWidget.__init__(self, parent)\n",
    "\n",
    "        ############# Diff ###############\n",
    "        # We represent the viewer as a camera\n",
    "        # The code can be a little strange\n",
    "        # to those who are not used to graphics\n",
    "        # programming. In our helper code,\n",
    "        # we had provided a pure python \n",
    "        # implementation and a Qt version\n",
    "        # which uses qt objects.\n",
    "        \n",
    "        # The values we set here are important\n",
    "        # for setting up the view matrix\n",
    "        # camera\n",
    "        self.camera = QtCamera()\n",
    "        self.camera.position = QVector3D(0.0, 0.0, 3.0)\n",
    "        self.camera.front = QVector3D(0.0, 0.0, -1.0)\n",
    "        self.camera.up = QVector3D(0.0, 1.0, 0.0)\n",
    "\n",
    "        # shaders etc\n",
    "        tutoTutoDir = os.path.dirname(__file__)\n",
    "        tutoPardir = os.path.join(tutoTutoDir, os.pardir)\n",
    "        tutoPardir = os.path.realpath(tutoPardir)\n",
    "        mediaDir = os.path.join(tutoPardir, \"media\")\n",
    "        shaderDir = os.path.join(mediaDir, \"shaders\")\n",
    "\n",
    "        availableShaders = [\"cube\"]\n",
    "        self.shaders = {\n",
    "            name: {\n",
    "                \"fragment\": os.path.join(shaderDir, name + \".frag\"),\n",
    "                \"vertex\": os.path.join(shaderDir, name + \".vert\")\n",
    "            } for name in availableShaders\n",
    "        }\n",
    "        self.core = \"--coreprofile\" in QCoreApplication.arguments()\n",
    "        imdir = os.path.join(mediaDir, \"images\")\n",
    "        imFName = \"im\"\n",
    "        imageFile1 = os.path.join(imdir, imFName + \"0.png\")\n",
    "        self.image1 = QImage(imageFile1).mirrored()\n",
    "        \n",
    "        ################ Diff #################\n",
    "        # We are going to use 2 textures.\n",
    "        # we shall see usage differences\n",
    "        # as we go along the code.\n",
    "        imageFile2 = os.path.join(imdir, imFName + \"1.png\")\n",
    "        self.image2 = QImage(imageFile2).mirrored()\n",
    "\n",
    "        # opengl data related\n",
    "        self.context = QOpenGLContext()\n",
    "        self.vao = QOpenGLVertexArrayObject()\n",
    "        self.vbo = QOpenGLBuffer(QOpenGLBuffer.VertexBuffer)\n",
    "        self.program = QOpenGLShaderProgram()\n",
    "        self.texture1 = None\n",
    "        self.texture2 = None\n",
    "        self.texUnit1 = 0\n",
    "        self.texUnit2 = 1\n",
    "\n",
    "        ############## Diff ##############\n",
    "        # cube is made up of 6 sides each side \n",
    "        # is a square which is made up of 2\n",
    "        # triangles and for each triangle we\n",
    "        # specify 3 corners\n",
    "        self.cubeVertices = np.array([\n",
    "            # pos vec3 || texcoord vec2\n",
    "            -0.5, -0.5, -0.5, 0.0, 0.0,\n",
    "            0.5, -0.5, -0.5, 1.0, 0.0,\n",
    "            0.5,  0.5, -0.5,  1.0, 1.0,\n",
    "            0.5,  0.5, -0.5,  1.0, 1.0,\n",
    "            -0.5,  0.5, -0.5,  0.0, 1.0,\n",
    "            -0.5, -0.5, -0.5,  0.0, 0.0,\n",
    "\n",
    "            -0.5, -0.5,  0.5,  0.0, 0.0,\n",
    "            0.5, -0.5,  0.5,  1.0, 0.0,\n",
    "            0.5,  0.5,  0.5,  1.0, 1.0,\n",
    "            0.5,  0.5,  0.5,  1.0, 1.0,\n",
    "            -0.5,  0.5,  0.5,  0.0, 1.0,\n",
    "            -0.5, -0.5,  0.5,  0.0, 0.0,\n",
    "\n",
    "            -0.5,  0.5,  0.5,  1.0, 0.0,\n",
    "            -0.5,  0.5, -0.5,  1.0, 1.0,\n",
    "            -0.5, -0.5, -0.5,  0.0, 1.0,\n",
    "            -0.5, -0.5, -0.5,  0.0, 1.0,\n",
    "            -0.5, -0.5,  0.5,  0.0, 0.0,\n",
    "            -0.5,  0.5,  0.5,  1.0, 0.0,\n",
    "\n",
    "            0.5,  0.5,  0.5,  1.0, 0.0,\n",
    "            0.5,  0.5, -0.5,  1.0, 1.0,\n",
    "            0.5, -0.5, -0.5,  0.0, 1.0,\n",
    "            0.5, -0.5, -0.5,  0.0, 1.0,\n",
    "            0.5, -0.5,  0.5,  0.0, 0.0,\n",
    "            0.5,  0.5,  0.5,  1.0, 0.0,\n",
    "\n",
    "            -0.5, -0.5, -0.5,  0.0, 1.0,\n",
    "            0.5, -0.5, -0.5,  1.0, 1.0,\n",
    "            0.5, -0.5,  0.5,  1.0, 0.0,\n",
    "            0.5, -0.5,  0.5,  1.0, 0.0,\n",
    "            -0.5, -0.5,  0.5,  0.0, 0.0,\n",
    "            -0.5, -0.5, -0.5,  0.0, 1.0,\n",
    "\n",
    "            -0.5,  0.5, -0.5,  0.0, 1.0,\n",
    "            0.5,  0.5, -0.5,  1.0, 1.0,\n",
    "            0.5,  0.5,  0.5,  1.0, 0.0,\n",
    "            0.5,  0.5,  0.5,  1.0, 0.0,\n",
    "            -0.5,  0.5,  0.5,  0.0, 0.0,\n",
    "            -0.5,  0.5, -0.5,  0.0, 1.0\n",
    "        ], dtype=ctypes.c_float\n",
    "        )\n",
    "        ############ Diff ##############\n",
    "        # As we can see there are 10 cubes.\n",
    "        # the cubes shape is described by the\n",
    "        # cubeVertices.\n",
    "        # We are going to render in the world.\n",
    "        # These are their positions.\n",
    "        self.cubeCoords = [\n",
    "            QVector3D(0.0,  0.0,  0.0),\n",
    "            QVector3D(2.0,  5.0, -15.0),\n",
    "            QVector3D(-1.5, -2.2, -2.5),\n",
    "            QVector3D(-3.8, -2.0, -12.3),\n",
    "            QVector3D(2.4, -0.4, -3.5),\n",
    "            QVector3D(-1.7,  3.0, -7.5),\n",
    "            QVector3D(1.3, -2.0, -2.5),\n",
    "            QVector3D(1.5,  2.0, -2.5),\n",
    "            QVector3D(1.5,  0.2, -1.5),\n",
    "            QVector3D(-1.3,  1.0, -1.5)\n",
    "        ]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Please inspect the code of `camera.py` when you have the time.\n",
    "The pure implementation should give you a rough idea about how everything works.\n",
    "Qt implementation simply facilitates the operations defined in the pure one by using qt objects.\n",
    "\n",
    "You should note that it is not very feasible to draw anything that is not geometric by specifying the vertices by hand. \n",
    "If you are looking to render real objects you should think about using a 3d modelling software like blender for example.\n",
    "\n",
    "Now let's see the initialization code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "    def initializeGL(self):\n",
    "        print('gl initial')\n",
    "        print(self.getGlInfo())\n",
    "\n",
    "        # create context and make it current\n",
    "        self.context.create()\n",
    "        self.context.aboutToBeDestroyed.connect(\n",
    "            self.cleanUpGl)\n",
    "\n",
    "        # initialize functions\n",
    "        funcs = self.context.functions()\n",
    "        funcs.initializeOpenGLFunctions()\n",
    "        funcs.glClearColor(0.0, 0.4, 0.4, 0)\n",
    "        ################## Diff ####################\n",
    "        # This readies opengl to render 3d graphics\n",
    "        funcs.glEnable(pygl.GL_DEPTH_TEST)\n",
    "        #\n",
    "        funcs.glEnable(pygl.GL_TEXTURE_2D)\n",
    "\n",
    "        # cube shader\n",
    "        self.program = QOpenGLShaderProgram(\n",
    "            self.context\n",
    "        )\n",
    "        vshader = self.loadVertexShader(\"cube\")\n",
    "        fshader = self.loadFragmentShader(\"cube\")\n",
    "        self.program.addShader(vshader)  # adding vertex shader\n",
    "        self.program.addShader(fshader)  # adding fragment shader\n",
    "        self.program.bindAttributeLocation(\n",
    "            \"aPos\", 0)\n",
    "        self.program.bindAttributeLocation(\n",
    "            \"aTexCoord\", 1)\n",
    "\n",
    "        isLinked = self.program.link()\n",
    "        print(\"cube shader program is linked: \",\n",
    "              isLinked)\n",
    "        # bind the program\n",
    "        self.program.bind()\n",
    "\n",
    "        ############### Diff ###############\n",
    "        # We define the projection matrix here\n",
    "        # for its function see our introduction\n",
    "        # set projection matrix. Please do note\n",
    "        # that we are using a perspective \n",
    "        # projection yet this is not the only\n",
    "        # projection type that is available\n",
    "        projectionMatrix = QMatrix4x4()\n",
    "        projectionMatrix.perspective(\n",
    "            self.camera.zoom,\n",
    "            self.width() / self.height(),\n",
    "            0.2, 100.0)\n",
    "        \n",
    "        # we set its value just like any other\n",
    "        # uniform\n",
    "        self.program.setUniformValue('projection',\n",
    "                                     projectionMatrix)\n",
    "\n",
    "        ############## Diff ##################\n",
    "        # As stated above, camera, being a fps\n",
    "        # style camera, gives us the matrix\n",
    "        # that help us to transform all the other\n",
    "        # coordinates with respect to the viewer.\n",
    "        # Meaning that the viewer is considered \n",
    "        # as the center and all other coordinates\n",
    "        # are redefined with respect to that coordinate\n",
    "        # Notice that this does not mean we have to redefine\n",
    "        # each object individually we just need to \n",
    "        # have the matrix that would give us \n",
    "        # the stated coordinate when we apply\n",
    "        # the transformation.\n",
    "        # set view/camera matrix\n",
    "        viewMatrix = self.camera.getViewMatrix()\n",
    "        self.program.setUniformValue('view',\n",
    "                                     viewMatrix)\n",
    "        \n",
    "        ################# Diff ####################\n",
    "        # The numbers set here are units for the samplers\n",
    "        # they are going to be important when we are creating\n",
    "        # the textures\n",
    "        self.program.setUniformValue('myTexture1', self.texUnit1)\n",
    "        self.program.setUniformValue('myTexture2', self.texUnit2)\n",
    "        #\n",
    "        # deal with vaos and vbo\n",
    "        # vbo\n",
    "        isVbo = self.vbo.create()\n",
    "        isVboBound = self.vbo.bind()\n",
    "\n",
    "        floatSize = ctypes.sizeof(ctypes.c_float)\n",
    "\n",
    "        # allocate space on vbo buffer\n",
    "        self.vbo.allocate(\n",
    "            self.cubeVertices.tobytes(),\n",
    "            floatSize * self.cubeVertices.size)\n",
    "        \n",
    "        # contary to texture tutorial\n",
    "        # we are going to reuse the old method \n",
    "        # for creating the vertex array objects\n",
    "        self.vao.create()\n",
    "        \n",
    "        vaoBinder = QOpenGLVertexArrayObject.Binder(self.vao)\n",
    "        funcs.glEnableVertexAttribArray(0)  # viewport\n",
    "        funcs.glVertexAttribPointer(0,\n",
    "                                    3,\n",
    "                                    int(pygl.GL_FLOAT),\n",
    "                                    int(pygl.GL_FALSE),\n",
    "                                    5 * floatSize,\n",
    "                                    VoidPtr(0)\n",
    "                                    )\n",
    "        funcs.glEnableVertexAttribArray(1)\n",
    "        funcs.glVertexAttribPointer(1,\n",
    "                                    2,\n",
    "                                    int(pygl.GL_FLOAT),\n",
    "                                    int(pygl.GL_FALSE),\n",
    "                                    5 * floatSize,\n",
    "                                    VoidPtr(3 * floatSize)\n",
    "                                    )\n",
    "        # deal with textures\n",
    "        # first texture\n",
    "        self.texture1 = QOpenGLTexture(\n",
    "            QOpenGLTexture.Target2D)\n",
    "        self.texture1.create()\n",
    "        ################# Diff ##################\n",
    "        # We bind the texture to a specific\n",
    "        # unit. This is necessary for the\n",
    "        # sampler. \n",
    "        self.texture1.bind(self.texUnit1)\n",
    "        self.texture1.setData(self.image1)\n",
    "        self.texture1.setMinMagFilters(\n",
    "            QOpenGLTexture.Nearest,\n",
    "            QOpenGLTexture.Nearest)\n",
    "        self.texture1.setWrapMode(\n",
    "            QOpenGLTexture.DirectionS,\n",
    "            QOpenGLTexture.Repeat)\n",
    "        self.texture1.setWrapMode(\n",
    "            QOpenGLTexture.DirectionT,\n",
    "            QOpenGLTexture.Repeat)\n",
    "\n",
    "        # second texture\n",
    "        self.texture2 = QOpenGLTexture(\n",
    "            QOpenGLTexture.Target2D)\n",
    "        self.texture2.create()\n",
    "        self.texture2.bind(self.texUnit2)\n",
    "        self.texture2.setData(self.image2)\n",
    "        self.texture2.setMinMagFilters(\n",
    "            QOpenGLTexture.Linear,\n",
    "            QOpenGLTexture.Linear)\n",
    "        self.texture2.setWrapMode(\n",
    "            QOpenGLTexture.DirectionS,\n",
    "            QOpenGLTexture.Repeat)\n",
    "        self.texture2.setWrapMode(\n",
    "            QOpenGLTexture.DirectionT,\n",
    "            QOpenGLTexture.Repeat)\n",
    "\n",
    "        self.vbo.release()\n",
    "        vaoBinder = None\n",
    "        print(\"gl initialized\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It might be a little daunting to take all that at once.\n",
    "But most of it should be familiar by now if you have followed previous tutorials.\n",
    "\n",
    "Now let's see the drawing loop."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "    def paintGL(self):\n",
    "        \"drawing loop\"\n",
    "        funcs = self.context.functions()\n",
    "\n",
    "        # clean up what was drawn\n",
    "        ############### Diff ##############\n",
    "        # Notice we clear the depth buffer \n",
    "        # as well\n",
    "        funcs.glClear(\n",
    "            pygl.GL_COLOR_BUFFER_BIT | pygl.GL_DEPTH_BUFFER_BIT\n",
    "        )\n",
    "        self.vao.bind()\n",
    "        self.vbo.bind()\n",
    "\n",
    "        # actual drawing\n",
    "        self.program.bind()\n",
    "        \n",
    "        ################## Diff ###################\n",
    "        # This is the first time we are drawing\n",
    "        # several objects. So we are going to call \n",
    "        # several glDrawArrays several times.\n",
    "        # Notice also that we are not changing the\n",
    "        # shape of the cube we are simply changing\n",
    "        # its rotation. The translate function\n",
    "        # simply multiplies the model matrix\n",
    "        # with a translation 4x4 matrix constructed\n",
    "        # from the position 3d vector. Translation\n",
    "        # matrix is essentially same except for\n",
    "        # its last column whose first three rows\n",
    "        # are made up of vectors components\n",
    "        rotvec = QVector3D(0.7, 0.2, 0.5)\n",
    "        # bind textures\n",
    "        for i, pos in enumerate(self.cubeCoords):\n",
    "            #\n",
    "            cubeModel = QMatrix4x4()\n",
    "            cubeModel.translate(pos)\n",
    "            angle = 30 * i\n",
    "            cubeModel.rotate(angle, rotvec)\n",
    "            self.program.setUniformValue(\"model\",\n",
    "                                         cubeModel)\n",
    "            self.texture1.bind(self.texUnit1)\n",
    "            self.texture2.bind(self.texUnit2)\n",
    "            funcs.glDrawArrays(\n",
    "                pygl.GL_TRIANGLES,\n",
    "                0,\n",
    "                self.cubeVertices.size\n",
    "            )\n",
    "        self.vbo.release()\n",
    "        self.program.release()\n",
    "        self.texture1.release()\n",
    "        self.texture2.release()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's it. \n",
    "\n",
    "We have covered a lot of grounds in this tutorial. \n",
    "It is normal if you are a bit lost.\n",
    "\n",
    "If you are not sure how all transformations work,\n",
    "checkout the section from <a href=\"https://learnopengl.com/Getting-started/Coordinate-Systems\">LearnOpenGL</a>. \n",
    "\n",
    "If you want to know more about how a camera works,\n",
    "checkout from the <a href=\"https://learnopengl.com/Getting-started/Camera\">same</a>."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}