Tucano  0.1
A library for rapid prototyping with modern OpenGL and GLSL
Tucano::Framebuffer Class Reference

A wrapper class for creating and using FBOs. More...

#include <framebuffer.hpp>

Public Member Functions

 Framebuffer (int w, int h, int num_buffers=1, GLenum textype=GL_TEXTURE_2D, GLenum int_frm=GL_RGBA32F, GLenum frm=GL_RGBA, GLenum pix_type=GL_UNSIGNED_BYTE)
 Framebuffer default constructor. More...
 
 Framebuffer (void)
 Framebuffer default empty constructor. More...
 
void create (int w, int h, int num_attachs=1, int nsamples=1)
 Creates the framebuffer with specified parameters. More...
 
void create (Eigen::Vector2i size, int num_attachs=1, int nsamples=1)
 
int bufferElements () const
 Returns the total number of data elements held by the framebuffer, in terms of red, green, blue and alpha components. Use this method if you need to allocate a buffer large enough to copy the framebuffer's contents. More...
 
int depthBufferElements () const
 Returns the total number of depth data elements held by the framebuffer. Use this method if you need to allocate a buffer large enough to copy the framebuffer's depth contents. More...
 
GLuint getTexID (int tex_id)
 Returns the id of the texture in given color attachment. More...
 
TexturegetTexture (int tex_id)
 Returns a pointer to a texture (attachment). More...
 
GLenum textureType (void)
 
void fillTexture (int attach_id, GLubyte *data)
 Fills a texture with given data in an array of Bytes. More...
 
void fillTexture (int attach_id, GLfloat *data)
 Fill a texture with given data in an array of Floats. More...
 
virtual void bind (void)
 Binds framebuffer object. More...
 
virtual void bindRenderBuffer (GLuint attachID)
 Bind framebuffer object and set render buffer to given attachment. More...
 
virtual void bindRenderBuffers (GLuint attachID0, GLuint attachID1)
 Bind framebuffer object and set render buffer to 2 given attachments. More...
 
virtual void bindRenderBuffers (GLuint attachID0, GLuint attachID1, GLuint attachID2)
 Bind framebuffer object and set render buffer to 3 given attachments. More...
 
virtual void bindRenderBuffers (GLuint attachID0, GLuint attachID1, GLuint attachID2, GLuint attachID3)
 Bind framebuffer object and set render buffer to 4 given attachments. More...
 
virtual void bindRenderBuffers (GLuint attachID0, GLuint attachID1, GLuint attachID2, GLuint attachID3, GLuint attachID4)
 Bind framebuffer object and set render buffer to 5 given attachments. More...
 
virtual void bindRenderBuffers (GLuint attachID0, GLuint attachID1, GLuint attachID2, GLuint attachID3, GLuint attachID4, GLuint attachID5)
 Bind framebuffer object and set render buffer to 6 given attachments. More...
 
virtual void bindRenderBuffers (GLuint attachID0, GLuint attachID1, GLuint attachID2, GLuint attachID3, GLuint attachID4, GLuint attachID5, GLuint attachID6)
 Bind framebuffer object and set render buffer to 7 given attachments. More...
 
virtual void bindRenderBuffers (GLuint attachID0, GLuint attachID1, GLuint attachID2, GLuint attachID3, GLuint attachID4, GLuint attachID5, GLuint attachID6, GLuint attachID7)
 Bind framebuffer object and set render buffer to 8 given attachments. More...
 
virtual void bindRenderBuffers (GLsizei n, GLuint *buffers)
 Bind framebuffer object and set render buffer to given array of buffers. More...
 
virtual void unbindFBO (void)
 Unbinds framebuffer object. More...
 
void unbind (void)
 Unbinds fbo and all texture units in use. More...
 
void blitTo (Framebuffer &copyfbo, int source_attach=0, int dest_attach=0)
 Copy fbo attachment to another fbo with blit operation. More...
 
Eigen::Vector2i getSize () const
 Returns the framebuffer's dimensions as a 2-component vector. More...
 
void clearAttachments (Eigen::Vector4f clear_color=Eigen::Vector4f::Zero())
 Clears all attachments with a given color. More...
 
void clearAttachment (int attachment, Eigen::Vector4f clear_color=Eigen::Vector4f::Zero())
 Clears a given attachments with a given color. More...
 
void clearDepth (void)
 Clears the FBO depthbuffer. More...
 
void bindAttachment (int attachment, int texture_unit)
 Binds a texture attachment to a given texture unit. More...
 
int bindAttachment (int attachment)
 Binds a texture attachment to the first free unit. More...
 
void unbindAttachments (void)
 Unbinds all texture attachments. More...
 
void setInternalFormat (GLenum int_frm)
 Sets the internal format of the FBO's texture. More...
 
void setInputFormat (GLenum in_format)
 Sets format to read data to the FBO. More...
 
void setInputType (GLenum in_type)
 Sets data type for reading pixels to the FBO. More...
 
void setTextureType (GLenum tex_type)
 Sets FBO texture type. More...
 
Eigen::Vector4f readPixel (int attach, Eigen::Vector2i pos)
 Reads a pixel from a buffer and returns it as an Eigen vector. More...
 
void readBuffer (int attach_id, GLfloat **pixels)
 Reads a GPU buffer and stores it in a CPU array of floats. More...
 
void readBuffer (int attach_id, GLbyte **pixels)
 Reads a GPU buffer and stores it in a CPU array of unsigned bytes. More...
 
void readBuffer (int attach_id, unsigned char **pixels)
 Reads a GPU buffer and stores it in a CPU array of unsigned char. More...
 
void readBuffer (int attach_id, vector< unsigned char > &pixels)
 Reads a GPU buffer and stores it in a CPU vector of unsigned char. More...
 
void readBuffer (int attach_id, vector< float > &pixels)
 Reads a GPU buffer and stores it in a CPU vector of float. More...
 
void readDepthBuffer (vector< GLbyte > &depth_values)
 Reads the depth buffer and stores it in a CPU vector of GLbyte. More...
 
void readDepthBuffer (vector< float > &depth_values)
 Reads the depth buffer and stores it in a CPU vector of float. More...
 
void saveAsPPM (string filename, int attach=0)
 Saves the buffer to a PPM image. More...
 
void printBuffer (int attach, Eigen::Vector4f exception=Eigen::Vector4f(0.0, 0.0, 0.0, 0.0))
 Prints the content of a GPU. Usually used for debugging. More...
 
GLuint getID (void)
 Returns the fbo ID. More...
 
Eigen::Vector2i getDimensions (void)
 Returns the dimensions of the FBO. More...
 
int getWidth (void)
 Returns the width of the FBO. More...
 
int getHeight (void)
 Returns the height of the FBO. More...
 
int getNumAttachments (void)
 Returns the number of attachments. More...
 
bool isBinded (void)
 Returns wether the FBO is currently binded or not. More...
 

Protected Member Functions

virtual void createFramebuffer (int viewportWidth, int viewportHeight, int numberOfTextures=1)
 Creates the framebuffer and the depthbuffer. More...
 
virtual void createTexture (int attach_id)
 Generate the ith FBO texture as the ith color attachment. More...
 

Protected Attributes

GLuint fbo_id
 The Framebuffer Object. More...
 
GLuint depthbuffer_id
 The Depthbuffer Object. More...
 
std::vector< TexturefboTextures
 Array of textures attachments. More...
 
GLenum texture_type
 Texture type for framebuffer attachments, default is GL_TEXTURE_2D. More...
 
Eigen::Vector2i size
 Framebuffer dimensions. More...
 
GLenum internal_format
 Internal format as defined by OpenGL (ex. GL_RGBA, GL_RGBA32F ...). More...
 
GLenum pixel_type
 Pixel type (GL_FLOAT, GL_UNSIGNED_INT ...) More...
 
GLenum format
 Format as defined by OpenGL (ex. GL_RGBA, GL_RGBA_INTEGER ...) More...
 
int num_samples = 1
 Number of samples (for multisampling) More...
 
bool is_binded
 Flag to indicate if buffer is binded or not. More...
 
std::shared_ptr< GLuint > fboID_sptr
 Shared pointer to fbo id. More...
 
std::shared_ptr< GLuint > depthbufferID_sptr
 Shared pointer to depth buffer id. More...
 

Detailed Description

A wrapper class for creating and using FBOs.

The Framebuffer class is responsible for framebuffer generation and storage. It holds many shortcut methods to bind, draw to buffer, read buffer for debug, etc...

Constructor & Destructor Documentation

Tucano::Framebuffer::Framebuffer ( int  w,
int  h,
int  num_buffers = 1,
GLenum  textype = GL_TEXTURE_2D,
GLenum  int_frm = GL_RGBA32F,
GLenum  frm = GL_RGBA,
GLenum  pix_type = GL_UNSIGNED_BYTE 
)
inline

Framebuffer default constructor.

Creates a framebuffer with the given size and number of buffers, as well as set all texture units as not used.

Parameters
wWidth of the framebuffer texture object.
hHeight of the framebuffer texture object.
num_buffersNumber of textures that the framebuffer object will hold.
textypeType of the framebuffer texture object.
int_frmInternal format (default is GL_RGBA32F)
frmFormat (default is GL_RGBA)
pix_typeTexture pixel type (default is GL_FLOAT)
Tucano::Framebuffer::Framebuffer ( void  )
inline

Framebuffer default empty constructor.

Member Function Documentation

virtual void Tucano::Framebuffer::bind ( void  )
inlinevirtual

Binds framebuffer object.

void Tucano::Framebuffer::bindAttachment ( int  attachment,
int  texture_unit 
)
inline

Binds a texture attachment to a given texture unit.

Parameters
attachmentNumber of color attachment.
texture_unitNumber of unit to bind texture.
int Tucano::Framebuffer::bindAttachment ( int  attachment)
inline

Binds a texture attachment to the first free unit.

Parameters
attachmentNumber of color attachment
Returns
Number of unit attached, or -1 if no unit available.
virtual void Tucano::Framebuffer::bindRenderBuffer ( GLuint  attachID)
inlinevirtual

Bind framebuffer object and set render buffer to given attachment.

Parameters
attachIDThe color attachment to be used for writing.
virtual void Tucano::Framebuffer::bindRenderBuffers ( GLuint  attachID0,
GLuint  attachID1 
)
inlinevirtual

Bind framebuffer object and set render buffer to 2 given attachments.

Parameters
attachID0The first color attachment to be used for writing.
attachID1The second color attachment to be used for writing.
virtual void Tucano::Framebuffer::bindRenderBuffers ( GLuint  attachID0,
GLuint  attachID1,
GLuint  attachID2 
)
inlinevirtual

Bind framebuffer object and set render buffer to 3 given attachments.

Parameters
attachID0The first color attachment to be used for writing.
attachID1The second color attachment to be used for writing.
attachID2The third color attachment to be used for writing.
virtual void Tucano::Framebuffer::bindRenderBuffers ( GLuint  attachID0,
GLuint  attachID1,
GLuint  attachID2,
GLuint  attachID3 
)
inlinevirtual

Bind framebuffer object and set render buffer to 4 given attachments.

Parameters
attachID0The first color attachment to be used for writing.
attachID1The second color attachment to be used for writing.
attachID2The third color attachment to be used for writing.
attachID3The fourth color attachment to be used for writing.
virtual void Tucano::Framebuffer::bindRenderBuffers ( GLuint  attachID0,
GLuint  attachID1,
GLuint  attachID2,
GLuint  attachID3,
GLuint  attachID4 
)
inlinevirtual

Bind framebuffer object and set render buffer to 5 given attachments.

Parameters
attachID0The first color attachment to be used for writing.
attachID1The second color attachment to be used for writing.
attachID2The third color attachment to be used for writing.
attachID3The fourth color attachment to be used for writing.
attachID4The fifth color attachment to be used for writing.
virtual void Tucano::Framebuffer::bindRenderBuffers ( GLuint  attachID0,
GLuint  attachID1,
GLuint  attachID2,
GLuint  attachID3,
GLuint  attachID4,
GLuint  attachID5 
)
inlinevirtual

Bind framebuffer object and set render buffer to 6 given attachments.

Parameters
attachID0The first color attachment to be used for writing.
attachID1The second color attachment to be used for writing.
attachID2The third color attachment to be used for writing.
attachID3The fourth color attachment to be used for writing.
attachID4The fifth color attachment to be used for writing.
attachID5The sixth color attachment to be used for writing.
virtual void Tucano::Framebuffer::bindRenderBuffers ( GLuint  attachID0,
GLuint  attachID1,
GLuint  attachID2,
GLuint  attachID3,
GLuint  attachID4,
GLuint  attachID5,
GLuint  attachID6 
)
inlinevirtual

Bind framebuffer object and set render buffer to 7 given attachments.

Parameters
attachID0The first color attachment to be used for writing.
attachID1The second color attachment to be used for writing.
attachID2The third color attachment to be used for writing.
attachID3The fourth color attachment to be used for writing.
attachID4The fifth color attachment to be used for writing.
attachID5The sixth color attachment to be used for writing.
attachID6The seventh color attachment to be used for writing.
virtual void Tucano::Framebuffer::bindRenderBuffers ( GLuint  attachID0,
GLuint  attachID1,
GLuint  attachID2,
GLuint  attachID3,
GLuint  attachID4,
GLuint  attachID5,
GLuint  attachID6,
GLuint  attachID7 
)
inlinevirtual

Bind framebuffer object and set render buffer to 8 given attachments.

Parameters
attachID0The first color attachment to be used for writing.
attachID1The second color attachment to be used for writing.
attachID2The third color attachment to be used for writing.
attachID3The fourth color attachment to be used for writing.
attachID4The fifth color attachment to be used for writing.
attachID5The sixth color attachment to be used for writing.
attachID6The seventh color attachment to be used for writing.
attachID7The eigth color attachment to be used for writing.
virtual void Tucano::Framebuffer::bindRenderBuffers ( GLsizei  n,
GLuint *  buffers 
)
inlinevirtual

Bind framebuffer object and set render buffer to given array of buffers.

Parameters
nNumber of attachments to be used for writing.
buffersArray of attachments to be used for writing.
void Tucano::Framebuffer::blitTo ( Framebuffer copyfbo,
int  source_attach = 0,
int  dest_attach = 0 
)
inline

Copy fbo attachment to another fbo with blit operation.

Parameters
copyfboPointer to destination FBO
source_attachSource attachment
dest_attachDestination attachment
int Tucano::Framebuffer::bufferElements ( ) const
inline

Returns the total number of data elements held by the framebuffer, in terms of red, green, blue and alpha components. Use this method if you need to allocate a buffer large enough to copy the framebuffer's contents.

Returns
The total number of elements stored by the framebuffer
void Tucano::Framebuffer::clearAttachment ( int  attachment,
Eigen::Vector4f  clear_color = Eigen::Vector4f::Zero() 
)
inline

Clears a given attachments with a given color.

Parameters
attachmentGiven texture attachment to be cleared.
clear_colorClear color (default is zero vector)
void Tucano::Framebuffer::clearAttachments ( Eigen::Vector4f  clear_color = Eigen::Vector4f::Zero())
inline

Clears all attachments with a given color.

Parameters
clear_colorClear color (default is zero vector).
void Tucano::Framebuffer::clearDepth ( void  )
inline

Clears the FBO depthbuffer.

void Tucano::Framebuffer::create ( int  w,
int  h,
int  num_attachs = 1,
int  nsamples = 1 
)
inline

Creates the framebuffer with specified parameters.

Parameters
wWidth of FBO.
hHeight of FBO.
num_attachsNumber of texture attachments to be created.
num_samplesNumber of samples, if more than 1 creates multisample texture.
void Tucano::Framebuffer::create ( Eigen::Vector2i  size,
int  num_attachs = 1,
int  nsamples = 1 
)
inline

Overload of create method to use vector2i instead of width and height

virtual void Tucano::Framebuffer::createFramebuffer ( int  viewportWidth,
int  viewportHeight,
int  numberOfTextures = 1 
)
inlineprotectedvirtual

Creates the framebuffer and the depthbuffer.

The viewport width and height are needed in order to create the FBO. The number of texture attachments may be greater than one. Note, however, that all textures of the FBO must have the same size (unless it is a MipMap) and parameters.

Parameters
viewportWidthThe current viewport width.
viewportHeightThe current viewport height.
numberOfTexturesNumber of output attachments
virtual void Tucano::Framebuffer::createTexture ( int  attach_id)
inlineprotectedvirtual

Generate the ith FBO texture as the ith color attachment.

Parameters
attach_idAttachment holding the texture.
int Tucano::Framebuffer::depthBufferElements ( ) const
inline

Returns the total number of depth data elements held by the framebuffer. Use this method if you need to allocate a buffer large enough to copy the framebuffer's depth contents.

Returns
The total number of depth elements stored by the framebuffer
void Tucano::Framebuffer::fillTexture ( int  attach_id,
GLubyte *  data 
)
inline

Fills a texture with given data in an array of Bytes.

Parameters
attach_idAttachment of texture to be filled.
dataPointer to the data.
void Tucano::Framebuffer::fillTexture ( int  attach_id,
GLfloat *  data 
)
inline

Fill a texture with given data in an array of Floats.

Parameters
attach_idAttachment of texture to be filled.
dataPointer to the data.
Eigen::Vector2i Tucano::Framebuffer::getDimensions ( void  )
inline

Returns the dimensions of the FBO.

Returns
The dimensions of the FBO
int Tucano::Framebuffer::getHeight ( void  )
inline

Returns the height of the FBO.

Returns
The height of the FBO
GLuint Tucano::Framebuffer::getID ( void  )
inline

Returns the fbo ID.

Returns
FBO ID
int Tucano::Framebuffer::getNumAttachments ( void  )
inline

Returns the number of attachments.

Returns
Numbre of attachments.
Eigen::Vector2i Tucano::Framebuffer::getSize ( ) const
inline

Returns the framebuffer's dimensions as a 2-component vector.

Returns
The framebuffer's dimensions.
GLuint Tucano::Framebuffer::getTexID ( int  tex_id)
inline

Returns the id of the texture in given color attachment.

Parameters
tex_idPosition of the texture, as in the ith texture of the FBO.
Returns
ID of the texture, the OpenGL handle for the texture.
Texture* Tucano::Framebuffer::getTexture ( int  tex_id)
inline

Returns a pointer to a texture (attachment).

Parameters
tex_idPosition of the texture, as in the ith texture of the FBO.
Returns
Pointer to the texture.
int Tucano::Framebuffer::getWidth ( void  )
inline

Returns the width of the FBO.

Returns
The width of the FBO
bool Tucano::Framebuffer::isBinded ( void  )
inline

Returns wether the FBO is currently binded or not.

Returns
True if FBO is binded, false otherwise.
void Tucano::Framebuffer::printBuffer ( int  attach,
Eigen::Vector4f  exception = Eigen::Vector4f(0.0,0.0,0.0,0.0) 
)
inline

Prints the content of a GPU. Usually used for debugging.

Assumes each pixel has four GLfloat elements.

Parameters
attachNumber of buffer to be read
exceptionPixel value that should not be printed, usually the background.
void Tucano::Framebuffer::readBuffer ( int  attach_id,
GLfloat **  pixels 
)
inline

Reads a GPU buffer and stores it in a CPU array of floats.

Assumes each pixel has four GLfloat elements. If pixels is not null, it is deallocated, then reallocated to ensure the array as large enough to store the framebuffer's contents.

Parameters
attach_idBuffer to be read, the id of the attachment.
pixelsPointer to array of pixels.
void Tucano::Framebuffer::readBuffer ( int  attach_id,
GLbyte **  pixels 
)
inline

Reads a GPU buffer and stores it in a CPU array of unsigned bytes.

Assumes each pixel has four GLBytes elements. If pixels is not null, it is deallocated, then reallocated to ensure the array as large enough to store the framebuffer's contents.

Parameters
attach_idBuffer to be read, the id of the attachment
pixelsPointer to array of pixels.
void Tucano::Framebuffer::readBuffer ( int  attach_id,
unsigned char **  pixels 
)
inline

Reads a GPU buffer and stores it in a CPU array of unsigned char.

Assumes each pixel has four unsigned char elements. If pixels is not null, it is deallocated, then reallocated to ensure the array as large enough to store the framebuffer's contents.

Parameters
attach_idBuffer to be read, the id of the attachment
pixelsPointer to array of pixels.
void Tucano::Framebuffer::readBuffer ( int  attach_id,
vector< unsigned char > &  pixels 
)
inline

Reads a GPU buffer and stores it in a CPU vector of unsigned char.

The vector is cleared prior to copying the framebuffer's contents.

Assumes each pixel has four unsigned char elements.

Parameters
attach_idBuffer to be read, the id of the attachment
pixelsVector of pixels.
void Tucano::Framebuffer::readBuffer ( int  attach_id,
vector< float > &  pixels 
)
inline

Reads a GPU buffer and stores it in a CPU vector of float.

The vector is cleared prior to copying the framebuffer's contents.

Assumes each pixel has four float elements.

Parameters
attach_idBuffer to be read, the id of the attachment.
pixelsVector of float pixels.
void Tucano::Framebuffer::readDepthBuffer ( vector< GLbyte > &  depth_values)
inline

Reads the depth buffer and stores it in a CPU vector of GLbyte.

Parameters
depth_valuesVector of GLbyte pixels to receive depth values.
void Tucano::Framebuffer::readDepthBuffer ( vector< float > &  depth_values)
inline

Reads the depth buffer and stores it in a CPU vector of float.

Parameters
depth_valuesVector of float pixels to receive depth values.
Eigen::Vector4f Tucano::Framebuffer::readPixel ( int  attach,
Eigen::Vector2i  pos 
)
inline

Reads a pixel from a buffer and returns it as an Eigen vector.

Assumes that a pixel has four GLfloat elements.

Parameters
attachBuffer to be read, the id of the attachment.
posPixel position to be read.
Returns
Read pixel as a vector of four floats.
void Tucano::Framebuffer::saveAsPPM ( string  filename,
int  attach = 0 
)
inline

Saves the buffer to a PPM image.

Parameters
filenameOutput ppm filename
attachFBO attachment to save as image (default is 0)
void Tucano::Framebuffer::setInputFormat ( GLenum  in_format)
inline

Sets format to read data to the FBO.

Default when created is GL_RGBA32F.

Parameters
in_formatGiven input data format.
void Tucano::Framebuffer::setInputType ( GLenum  in_type)
inline

Sets data type for reading pixels to the FBO.

Default when created is GL_FLOAT.

Parameters
in_typeGiven input data type.
void Tucano::Framebuffer::setInternalFormat ( GLenum  int_frm)
inline

Sets the internal format of the FBO's texture.

Default when created is GL_RGBA32F.

Parameters
int_frmInternal format.
void Tucano::Framebuffer::setTextureType ( GLenum  tex_type)
inline

Sets FBO texture type.

Default when created is GL_TEXTURE_2D.

Parameters
tex_typeGiven input data type.
GLenum Tucano::Framebuffer::textureType ( void  )
inline
Returns
The texture type of the texture attachments.
void Tucano::Framebuffer::unbind ( void  )
inline

Unbinds fbo and all texture units in use.

void Tucano::Framebuffer::unbindAttachments ( void  )
inline

Unbinds all texture attachments.

virtual void Tucano::Framebuffer::unbindFBO ( void  )
inlinevirtual

Unbinds framebuffer object.

Member Data Documentation

GLuint Tucano::Framebuffer::depthbuffer_id
protected

The Depthbuffer Object.

std::shared_ptr< GLuint > Tucano::Framebuffer::depthbufferID_sptr
protected

Shared pointer to depth buffer id.

GLuint Tucano::Framebuffer::fbo_id
protected

The Framebuffer Object.

std::shared_ptr< GLuint > Tucano::Framebuffer::fboID_sptr
protected

Shared pointer to fbo id.

std::vector<Texture> Tucano::Framebuffer::fboTextures
protected

Array of textures attachments.

GLenum Tucano::Framebuffer::format
protected

Format as defined by OpenGL (ex. GL_RGBA, GL_RGBA_INTEGER ...)

GLenum Tucano::Framebuffer::internal_format
protected

Internal format as defined by OpenGL (ex. GL_RGBA, GL_RGBA32F ...).

bool Tucano::Framebuffer::is_binded
protected

Flag to indicate if buffer is binded or not.

In operations where the buffer needs to be binded (such as read, clear, etc) it will be automatically binded and then unbided if flag is not currently binded, otherwise, if it was already binded, it will be left binded.

int Tucano::Framebuffer::num_samples = 1
protected

Number of samples (for multisampling)

GLenum Tucano::Framebuffer::pixel_type
protected

Pixel type (GL_FLOAT, GL_UNSIGNED_INT ...)

Eigen::Vector2i Tucano::Framebuffer::size
protected

Framebuffer dimensions.

GLenum Tucano::Framebuffer::texture_type
protected

Texture type for framebuffer attachments, default is GL_TEXTURE_2D.


The documentation for this class was generated from the following file: